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EDITOR'S NOTE 



CAROLINE ROSE 


Around the time 1 was faced with writing this editorial, I had just attended the 
celebration of my friend Mrs. Robertson's 100th birthday* and my 85-year-old lather 
had flown over from Florida to celebrate it with us. With the subject of longevity on 
my mind, 1 got to thinking about how it relates to develop * 

develop 's goal is to provide you with articles and code that will have a long life — that 
can live in your applications happily and compatibly even as new Macintosh systems 
are introduced. We do all we can to ensure this (at die risk of incurring the wrath of 
our authors, who may wonder why it takes so long to see something in print after 
iris submitted to develop). We’d rather an article “have legs” than be published 
prematurely and get you into trouble further down the line. We do our best to test 
the code and get our technical reviewers’ opinions on whether a particular method is 
safe. This should he a primary concern of all developers, especially now in tight of 
the whole new world of Power Macintosh systems* 


Evidence that we Ye succeeding is that we still get requests to reprint articles as fat- 
back as Issue 2, and we often hear from readers who save every issue because they 
retain their usefulness. (Remember that, the next time you Ye thinning out your 
bookshelves!) 


Our being an Apple publication gives us the distinct advantage of being able to have 
a thorough code review with future systems in mind, but at the same time it puts us 
in a unique position to have early articles on new Apple technology. So we also try to 
give you articles as soon as possible al ter the API for a new technology has frozen. 
And if we can, we give you a prerelease version of die new software along with die 
code on our CD. These articles may have somewhat shorter legs, but the bulk of the 
information should remain accurate for a very long time. 

In the past we’ve given you early QuickDraw GX versions and articles; now that 
QuickDraw GX has shipped, the two articles on that subject in this issue are only the 
most recent in a long line. Who in this issue we’re pleased to bring you our first 
article on OpenDoc, Apple’s new cross-platform compound-document architecture, 
even though the final version of OpenDoc will not have shipped by the lime you 
read this. 


Further evidence that we’re succeeding is that weVe again won in the International 
Technical Publications Competition of the Society for Technical Communication, 
this time the highest award in our category. But nothing would please us more than 
to hear from you, the most important judges of all, on what we can do to make 
develop an even better publication; please let us know at AppleLink DEVELOP. 

— 

Caroline Rose 
Editor 


CAROLINE ROSE (AppleLink CROSE) As a 
child, Caroline wrote a one-page newsletter 
about the goings-on in her neighborhood; it 
included news items, a gossip column, and o 
comic strip. Her readership was small, and the 
operation folded after one issue. She's happy that 
develop has lasted longer than that, because 


after various jobs at Tymshare, NeXT, and Apple 
□s a programmer writer, editor, and manager, 
she feels she's found her niche here. These days 
when Caroline's not at work she's likely to be 
sailing, swimming, jogging, doncing, gardening, 
or otherwise not being sedentary. She hopes to 
live 1 00 very active years. * 
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LETTERS 


MISSING GAME FOLDER 

The column by Brigham Stevens on 
game development in develop Issue 17 
refers to a Game Development folder 
on the Bookmark 17 CD. I was unable 
to locate the folder. Is Sr me, or was 
there a production glitch? 

Also, is the folder the same one that was 
on the February Developer CD? 

— Boh Boonstra 

There was a production glitch. The folder 
was on Issue 16 s Bookmark CD but was 
inadvertently removed from Issue 17 s CD. 
We have since restored it (its in the Tools & 
Applications folder). We also got the name 
wrong: it's Games, not Game Development. 

And yes, it s the same folder as the one on 
the Developer CD , The Bookmark CD 
always contains a subset of the Developer 
CD Series . 

Happy gaming! 

— Dave Joh nson 

DEVELOP ON THE SMALL SCREEN 

In Issue 17 you ask why so many 
applications lack common sense, and 
then you go on to list a number of 
annoyances caused by bad designs. I 
agree that the items mentioned could 
be better handled, but 1 have a similar 
complaint with develop! 

develop , ship pc d o n CD-RO / VI w i th 
Apple DocVIewer, is a software product 
rhats produced like a printed document. 
Things like double-columned pages are 
extremely difficult to read on a standard 
Macintosh 13-inch monitor —you have 
to scroll down the entire page as you 
read a single column and then scroll 


back up and repeat the process. While 
this orientation makes sense on a 
printed page, it really bites on my 13- 
inch monitor. Also, develop is nearly 
un re a d a b 1 e w i t h i ts se ri f type fa ce s, 
italics, etc. 

Right now you’re probably shaking your 
heat 1 and saying that you don’t have the 
money to produce two versions of 
develop — one for print and one for CD. 
If so, then you also know why so many 
applications lack common sense! 

— Brooks Bel 1 

Certainly time and money do enter into 
design decisions, even at Apple. But there 
are still a lot of cases where common sense 
could be followed without a big kit to the 
schedule or pocket book. 

Regarding your problem with viewing the 
CD version of develop on a 13-inch screen, 
you might t?y Dodd ewer's “text ” view (the 
icon in the tool bar that looks like a sheet of 
paper with writing, just to the left of the 
scaling pop-up menu). This view gets rid 
of all special formatting such as double 
columns. You can still look at illustrations, 
by clicking the Open button next to the 
figure caption. 

In text view you am change the font size 
and type of any structural part of the 
document , using the Format command in 
the Edit menu. For example 7 you can choose 
Body in the Format dialog and change the 
font of all the body text. (In the nonnal 
view , the scaling pop-up menu can he used 
to magnify everything.) 

Thanks for writing and giving us the 
opportunity to provide these tips. We 
welcome all gripes! 

—- Caroline Rose 


WE'Ri DYING TO HEAR FROM YOU 

We welcome timely letters to the editors, 
especially from readers reacting to articles that 
we publish in deve/op. Letters should be 
addressed to Caroline Rose (or, if technical 
devebp^related questions, to Dave Johnson) at 
Apple Computer, Inc., One Infinite Loop, M/S 


303-4DP, Cupertino, CA 95014 (AppleLink 
CROSE or JOHNSON.DK). All letters should 
include your name and company name as well as 
your address and phone number. Letters may be 
excerpted or edited for clarity [or to make them 
say what we wish they did).* 
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QUICKDRAW GX MORPH TABLES 

The Macintosh Q&A section ot develop 
Issue 16 stated that there’s no way to 
do an automatic checksum digit 
insertion using QuickDraw GX’s glyph 
metamorphosis tables, I haven’t read 
much about QuickDraw GX s 'mort' 
tables, but 1 do know finite state tables. 
It’s quite feasible to build a 12-state 
table that will generate a checksum digit 
for a digit-string of any length. The key 
is to make the checksum be calculated 
dynam\cally instead of at the end. This 
reduces die required number of states to 
ten, plus beginning and end, which is 
well within the limits of QuickDraw GX. 

— Mark Cogan 

D eve lope r Wan n a l )e 

You're quite right;you can indeed use 
morph tables to generate checksums. Other 
cyclic kinds of calcula tions are also possible: 
for example, a morph table could be set up 
to do pseudo-random selection of letterforms 
from a font that was designed zvitb five 
variant forms of A-Z and a-z . When a 
letter is encountered, it would be replaced 
with ks version from one of the sets. But 
regardless of the specific glyph, each time a 
glyph is processed the state advances and 
eventually loops back to the starting state. 
This is in general the template for how 
cyclic effects can be implemented with the 
QuickDraw GX morph tables. 

— Dave Opstad 

GX Line Layout Weenie 

WATCH-CURSOR PUSH-UPS 
AND BEYOND 

Regard i n g Dave J()hnson’s bi o in Issue 
16: He’s not the only one who plays with 
the cursor while waiting for the Mac. 
Here are some other silly things to do: 

* Try to fit the watch inside an empty 
hori zon ta I s cra 11 bar. 11 a I w ays over 1 a ps 
one of die lines, either the top or 
bottom one, so if you move diat single 
pixel that alternates between them, the 
watch seems to be slipping on its wrist 
belt, 

* While installing the system, position 
die counting hand so that it’s just 


touching a horizontal line. Don’t 
overlap the line, and the hand will seem 
to lie cut from its owner, instead of 
being a ghost unterminated hand, 

— J a vi e r Gue r r a G. 

Dave is not alone in doing watch-cursor 
push-ups and pull-ups. My personal 
favorite activity here is trying to find a 
place where I can do both at once. I 
remember that the old Font/D A Mover 
has a spot between two buttons where 
you can do that nicely. 

— Maarten Hazewinkel 

Hot Dawg! I knew there were others out 
their doing the watch cursor thing. Pve 
heard from a half dozen or so; IPs a lot more 
common than l thought. 

I remember doing that with the old 
Font/DA Mover, too. The progress bar 
during long Finder operations also worked 
well (Nowadays we have movable modal 
progress windows, so the watch cursor is 
gone — the price of progress.) 

Thanks for letting me know Vm not alone! 

— Dave Johnson 

UNABASHED PRAISE 

develop is an inspiring magazine. The 
layout is clean vet warm and inviting. 
The articles are relevant and the audiors 
arc knowlegeablc. 

Th e on-line issues of develop a re 
invaluable. This is the best on-line 
documentation 1 have seen, period. The 
articles look great — just like the 
magazine. And searching and setting 
fi 1 te rs i s fa s t. M i era so ft s CI > co mes 
with a lot of files, hut most of it is old, 
irrelevant, and ugly to read. 

I sure appreciate your effort. 

— Brent Foust 

We can i thank you enough for taking the 
time to write. Letters like this' keep us 
going , in more ways than one. We hope 
you 're as happy with the recent changes to 
our layout; please let us know if not 

— Caroline Rose 
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Building an OpenDoc Part Handler 


OpenDoc, Apple's compound-document architecture, brings users a new , 
more powerful metaphor for working with documents. Writing code to 
support OpenDoc is a lot like writing a normal application . This article 
gives an overview of what's involved in writing OpenDoc code and 
presents a simple working example. 



KURT PIERSOL 


OpenDoc provides a new way to write application code for die Macintosh anti a 
number of other desktop platforms* By following the OpenDoc guidelines, you can 
produce applications that share files, windows, and interface elements seamlessly* The 
process of writing an OpenDoc application, which we call a part bmdlm\ is much like 
w r i ti n g a n y Ma ci n tosh appl i ca ti on. Ther e a re d i f Fe re nces a s well, of course, and this 
article will help you understand them. 

OpenDoc applications are designed to allow code from several sources to cooperate 
in producing compound documents^ documents that can embed almost any kind of 
content inside them* Each piece of content in the document (each pan) includes its 
own part handler, the code that's used to edit and view it. To achieve this, OpenDoc 
part handlers must cooperate in a number of ways* They must sort out how events 
are passed, where data is stored on the disk, and where drawing is allowed to occur on 
windows or printed pages* 


This article starts with a brief overview of OpenDoc and then talks about 
implementing a simple part handler* It will show you the absolute basics, much as 
TESample does for TextEdit tn the Macintosh Toolbox* You’ll learn about a simple 
example of building a part handler, included on this issue's Cl3: a clock that can 
handle two different display modes, digital and analog. The clock updates itself every 
second and allows the user to select the display mode from a menu. 


A quick caveat: The sample code provided on the CD is from the alpha version of 
OpenDoc, hut by the time you read this, a beta version should be available. When 
you begin implementing your own part handler, you may find that some details of the 
API have changed; however, the overall structure will be the same* The sample clock, 
for instance, is specific to C++ and the alpha version of OpenDoc. The final version 
of OpenDoc w ill be based on IBM s System Object Model (SOM), which will allow 
part handlers to he w ritten in a variety of languages, both object-oriented and 
procedural. Similarly, the XMP prefix on OpenDoc class names (you'll see a lot of 
them in this article) will be changed to OD beginning with die beta release* 


KURT PIERSOL, the chief architect of OpenDoc, 
previously led the Apple Event project and was 
an early technical lead for AppleScript. He's 
responsible for making technologies fit together at 


Apple. Kurt also likes to wear suspenders, though 
that has very little to do with his software 
architectural responsibilities. * 
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This is perhaps a good rime to mention a bit more about SOM. This technology is 
ihe basic mechanism that OpenDoc part handlers use to communicate with one 
another SOM solves many hard problems associated with using object-oriented 
languages, including those of subclassing across language boundaries* altering base 
classes under dynam ic linking, and long-term maintenance of object-oriented APIs. 

OVERVIEW OF OPENDOC 

Before getting into the specifics of OpenDoc and how to write part handlers, well 
talk about some of the basic services you’ll see in OpenDoc and where your own code 
h ts i n to the (> penDoc a rchi te ctu re* 

PART HANDLERS 

Part handlers are what provide OpenDoc with its ability to handle different kinds of 
content in a single document* You, the developer community, will write the various 
parr handlers that plug into OpenDoc. 

Part handlers are a lot like existing applications. They handle events, draw anti print, 
and read and store data onto disk. Every part handler provides a series of entry points 
that allow OpenDoc to request any of these actions from the part handler. In 
addition, the API has a number of “bookkeeping calls, 11 which allow OpenDoc to 
provide undo services and notify part handlers when their environment has changed. 

Overall, there are about 50 calls in the OpenDoc part APT that a part needs to 
implement* This is a lot, but it actually maps fairly closely with the number of things 
you'd have to do to write any Macintosh application* In addition, you can ignore 
many of these calls in many cases. For instance, if you don’t allow embedding of other 
parts within your part, there are about ten calls that you can safely ignore. If you 
don’t update your display asynchronously, but simply wait for update calls, there are 
additional calls that you can ignore* In many typical cases, this means that you can 
build a part handler very quickly from existing code. 

Part handlers are packaged as shared libraries in the Macintosh version of OpenDoc* 
This won’t always be the case on other OpenDoc platforms, but you can count on the 
API being the same on all platforms. The alpha version of OpenDoc uses the Apple 
Shared Library Manager to dynamically link your part handler into OpenDoc, while 
the beta version will use SOM. These versions will have different linker behavior but 
will essentially require the same basic packaging of your code; a shared library. 

In either case, you’ll find that OpenDoc is an object-oriented API. That means 
you’ll he talking to OpenDoc objects, and your part handler will itself be an 
OpenDoc object (or set of objects). This doesn’t mean that your code has to be built 
from the ground up in C++, though* SOM w ill provide interfaces to many languages, 
including C. 

Because part handlers are themselves objects, we often refer to them as “part objects” 
or “parts” m conversation. In fact, what the user would call a “part 77 in a document is 
really the combination of some persistent data stored in the document file and a set of 
objects that OpenDoc uses to display and manipulate the stored data. OpenDoc 
chooses appropriate part handlers based on the type of data stored in the document* 

RUNTIME OBJECTS 

As we describe how to write a part handler, we’ll mention some runtime objects that 
interact with your code* In OpenDoc, these objects can be located at run rime using 
the session object (XMPSession), to which your part object will be given a pointer 
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when it’s initialized. The session object is very important because it’s your link to die 
rest of the Open Doc objects that are running in the document. 

There’s a whole list of objects that the session object makes available. Of these, only 
three will be important for the purposes of dus article: the arbitrator, the dispatcher, 
and the undo stack. 

* The arbitrator is an object of class XMPArbitrator* The arbitrator 
for a session is the place where part handlers register their 
ownership of certain resources. The menu bar, the keystroke 
stream, and the current selection are all examples of resources that 
the arbitrator tracks. 

* The dispatcher is the object that dispatches events to the various 
part handlers. It’s an object of class XMP Dispatcher* Ids used in 
our example as a way to register for background lime. 

* The undo stack is an object of class XMPUndo that allows 
Open Doc to support multilevel undo across part handler 
boundaries. 

Each of these objects will be discussed as ids encountered. 


A RUNNING START 

To give you a running start, weVe built a small object-oriented framework for parts 
that implements the direct interface to Open Doc. This framework is a precursor to 
the new part handler framework that Apple is building; and is included here simply as 
sample code. Our sample clock uses this framework. The good thing about the 
framework is that it clearly separates the work that any part handler must do to be 
Open Doc compliant from the specific work performed in putting up a clock. 

The framework divides the work of a part into three objects: a frame object, a facet 
object, and a part object. Open Doc itself doesn’t require that you create anything but 
a part object, but tor the sake of clarity the framework divides the labor among 
several smaller objects. Fur easy reference, here’s a list of the classes w ell be 
discussing throughout the article anti their corresponding source files, ineltided on 
the CD: ^ 


( Tart 
C Frame 
C Facet 
CC lock Part 
CClockFrame 
CClockFacet 


FWPa r t. h, FWP a rt. epp 
FWFra me. h, FWFra me. epp 
FWFa cc t. h, I r WFa cet. cp p 
C lock Par h, Clock Par. epp 
Clock Fra.h, Clock Fra.epp 
ClockFac.h, ClockFac.epp 


The classes defined by the framework generally start with the letter C\ hence the 
classes CPart, CFrame, and CFacet, These three parts are helper objects for three 
OpenDoc classes, XMPPart, XMPFrame, and XMPFacet. XMPPart objects are 
Open Doc part handlers: you'll subclass XMPPart when writing your own* OpenDoc 
uses the frame and facet objects to Kelp part handlers lay themselves out in a window* 
How these classes work together is probably the single most complex thing to 
understand in OpenDoc. 
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XMPPart, the class from which part handlers arc derived, is simply the base class of 
every OpenDoc part handler. It’s the class that actually handles the drawing, editing, 
and storage. Every part handler is an implementation of some subclass of XMPPart. 





CP art, in the framework, is a class derived from XMPPart. IPs just a default 
implementation of the basic XMPPart behavior* As such, CPart is a treasure trove of 
information about the correct way to “ignore” calls that aren’t interesting because 
your part handler doesn’t support embedding, update asynchronously, or use 
offsc re e n hi tinaps. 

Every part is embedded in another part, with the exception of the root part, the top- 
level part in each compound document. When a part is embedded in another part, 
there’s an object that’s used to store information about the shape of the embedded 
part. This boundary between a container and an embedded part is a frame — an 
instance of the class XMPFrame. Every frame lias a single part displayed inside it. 
The container actually embeds the frame; it knows nothing about the part inside. 

Any part can be displayed in several frames at the same time. This makes it easy for a 
part to be visible in several windows or to have several different presentations. For 
example, a charting part might want to have one frame displaying the chart and 
another allowing the data to be edited in a table, 

A facet (an instance of an XMPFacet object) is a visible part of a frame. There can be 
many facets displaying within any given frame. This is a useful property, for instance, 
when a container wants to “split” windows. 

Both XMPFrames and XMPFacets have a field, partlnfo, for storing information 
specific to the part being displayed. This is rather like a window refCon, a handy 
place to store information independent of the object itself The C Fra me and CFacet 
objects are designed to be plugged into the partlnfo fields of their XMPFrame and 
XMPFacet counterparts. The containing part creates the XMPFrame and XMPFacet 
objects and then allows your part handler to initialize their partlnfo fields. In the 
framework, die actual work of drawing the part on the screen is done in the CFacet 
object. The work of deciding what shape the embedded part will take is done in die 
CFrame object. As we describe the specific operations, we’ll point out the class in 
which the code resides. 

INITIALIZATION CODE 

The first hit of code we’ll consider is the initialization code for each part object. Each 
distinct part in a document gets an instance of the part object, so if there are seven 
little clocks running in different windows (or the same window, for that matter) there 
are seven instances of the clock part object. This means that you probably want to 
come up with a scheme to share any global data so that you aren’t wasting space with 
many copies of it. Rorh the Apple Shared Library Manager and SOM support 
systemwide global storage, so this should he straightforward. 

Resources are a special case. You’ll want to be very polite about not permanently 
fiddling with the resource chain or making assumptions about where your resource 
file is in the chain. We suggest saving the previous head of rhe resource chain, setting 
your file to be the end of the chain, and using the single-level resource calls (such as 
Get! IndResource) to find the resources you’re after. Since you’ll probably want to 
share the resources among separate instances of your part object, it may be better to 
detach the resources you get and manage them yourself instead of counting on any 
particular application heap to have the correct resource map. 

THE CONSTRUCTOR 

The first step in initialization is the constructor. You should never do anything that 
could possibly fail in a constructor. This pretty much limits you to operations like 
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setting pointer variables to NULL, setting numeric variables to appropriate values, 
and making similar assignments from constants. 

You can see a good example in ClockPar.cpp. The clock part simply sets up its fields 
with appropriate constant values. 

XMPPART::INITPART 

The next phase of initialization takes place in die InitPart method that every part 
object implements. The InitPart method is called by Open Doc after the part object 
has been created, and here you am attempt tilings that can fail. This is where you 
should attempt to allocate any extra memory you need for your part instance, get 
resources if you need them, and set up your persistent storage. 

Let's examine how Open Docs storage system looks to a part handler. When your 
part object is created, the InitPart method is passed a storage unit object in which yon 
can persistently store information. A storage unit is really just a list of named 
properties, each of which has one or more values. Each value is an entire stream, like an 
existing Macintosh file. You can do read, write, seek, insert, and delete operations on 
individual values. 

Each value has a type, much like the type code associated with a Macintosh file. Every 
property in a storage unit can have one or more values, each with their own type 
code. Thus, you can store multiple representations ol any property. You can make up 
any p roperty nanies you like. < )ne special property name, kX M PPropCon ten is, is 
used by Open Doc to determine which handler goes with which part at run time. 
Every part object should have a property named kXMPPropCon tents so that Open Doc 
can determine what part handler to run. 

In our sample, C Clock Part has an Initialize method* which is called by CPart:: InitPart. 
It sets up the menu bar for the clock and sets up a focus set for obtaining system 
resources from the arbitrator (more about this later). A good example of"code to set 
up persistent storage can be found in the implementation of ("Part. The framework 
calls its own method, called ( dieckAndAddFroperties, to make sure that die storage 
unit is set up correctly. 

DRAWING CODE 

Now that your initialization code is in place, you'll want to make sure you can get 
your part to draw onscreen. Open Doc will call your part with the Draw method and 
tell you which facet should he drawn. 

Our sample, CClockPart, inherits some code from CPart that asks the CFacet object 
to do the drawing. Notice, though, that before it does this, CPart::Draw sets up the 
graphics port lor draw ing using the clipping information from the facet. This is very 
similar to the basic drawing model for the Macintosh, where you draw using die 
appropriate graphics port and clipping region. You can find the rest of the drawing 
code in CCIockFacetuDraw. This code consists of just rhe straightforward QuickDraw 
calls and attendant calculations needed to display either the digital or the analog clock 
face. 

We use a utility class called CDrawTn ilia tor to set up the drawing environment 
reliably. The constructor of this class does all the work of setting the graphics port’s 
clipping region and origin. Later, the destructor restores die port to its previous state. 
This is a tricky hit of C++ coding that takes advantage of the object allocation 
behavior of stack-based objects in C++. 


develop [ssue 19 


September 1994 


10 





HANDLING LAYOUT 

One of the features of CClockPart is that it presents a round shape when it’s 
embedded. To do this, it uses the XMPFrame object’s layout negotiation features. 

To understand this, you need to understand the notions of canvas, shape, and 
transform in Open Doc. 

* A canvas is simply a drawing context. On the Macintosh it can be 
either a QuickDraw graphics port or a QuickDraw GX view port. 

* A shape is a way of describing an area of a canvas. Open Doc 
supports describing shapes in terms of polygons, regions, or 
rectangles on the Macintosh. 

* A transform is a geometric transformation appropriate to the type 
of canvas in use. In QuickDraw, the only transformation available 
is an offset. In QuickDraw GX, the transformations are much 
more powerful, capable of scaling, rotating, and offsets, as well as 
some more interesting transformations such as skewing. 

An Open Doc frame has a set of shapes associated with it. One, called the frame shape, 
is how the container tells an embedded object how to lay itself out. Your part handler 
should use the frame shape to decide what to display and how to lay it out. When 
your part is finished laying itself out, it can optionally specify to die container exactly 
what part of the frame shape it plans to use. This shape is called the used shape of the 
frame. Finally, the embedded part can specify an active shape t which is the subset oi 
the frame shape that you want to use for determining whether you receive a mouse 
event. Often the used shape and the active shape are set to he the same shape. The 
container can take care of filling in any areas left untouched by the part handler. 

For example, assume we have a dock part embedded in a word processor that does 
text wrapping. The word processor allows its embedded frames to be laid out as 
rectangles. When the clock is embedded, it uses the frame shape (the rectangle given 
by the word processor) to determine the size of die clock face. After determining the 
size, it sets its used and active shapes to match the shape of die round clock lace. The 
word processor is now free to wrap text around die round clock face, and any clicks in 
the rectangular frame shape that aren’t actually on the clock face are passed through 
to the word processor. Those clicks can he used to manipulate the text that’s wrapped 
close to the clock face. 

CClockPart negotiates to get the frame shape to match the clock’s round face. This 
works hut is not strictly necessary. Instead, it could simply set its used shape to match 
die round area of the clock. Father method will ensure diat the container knows how 
to dip any underlying parts so that they don’t draw in the clocks area. 

A quick aside about shape negotiation: Negotiation is rather straightforward in 
Open Doc, but knowledgeable programmers will notice that there is little support for 
constrained negotiation. This is not an oversight, but instead a fundamental design 
choice. It’s up to die embedding part to constrain layout according to its model of 
content. This means that constraint strategies like “Boxes & Glue” or “Springs & 

Wi re s” are the p r o v i n ce of you r part han d 1 er, not Q p en D oc. Yo u ea n im pi ement a ny 
of a number of layout constraint schemes on top of OpenDoc, but every part handler 
may constrain 1 ayout within its own frame, 

You can see what happens when the container reshapes the clock in the method 
CClockFrame::FrameShapeChanged. CClockFrame requests a round shape from the 
container and then invalidates the correct areas so that redrawing occurs. For most 
parts, the standard behavior is to redo die layout based on the new shape, update the 
active and used shapes of the frame, and then invalidate the proper areas. 
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EVENT HANDLING 

Our next area of implementation is the event handling for the dock part. This is 
much like writing the event handling for any Macintosh application, with one 
difference: you don't poll the system for events by calling WaitNextEvent. Instead, 
when there's an event for your part handler OpenDoc calls your part's Hand!eEvent 
method. 

XMPPART::HANDL£EVENT 

The code inside HandleEvent is usually a switch statement, just as in applications 
today. There are some minor differences, which arc nicely illustrated by the code that 
CClockPart inherits from CPart. This code effectively delegates the various events to 
code that can handle each event, using a switch statement. Notice the behavior for 
mouse-down events, which calls CFacet::HandlcMouscDown, which in turn causes 
the frame to become active if it isn't already. 

The notion of activation in Open Doc is closely tied to the object discussed briefly 
earlier, the arbitrator. An object is “active” if it owns some of the foci in the arbitrator. 
A focus is just a shared data structure or system service of some kind, such as the menu 
bar or keystroke stream. 

When CGlockFrame is told to activate, it requests a set of foci from die arbitrator. 

In this case, it wants the menus and selection focus. These two, with the addition of 
the keystroke stream, constitute the basic focus set that almost every part asks for 
when it wants to allow editing. You can find die code that sets up the focus set in 
CGlockFrame::InitClnckhrame. In GFrame::ActivateFrame, the focus set is 
requested. 

Notice that the part is requesting the menu focus before it attempts to put up its 
menu bar. This is die basic rule to follow in all cases* If there’s an arbitrator focus for 
the resource, you must request it and succeed in getting it before it's OK to use the 
resource. OpenDoc uses the arbitrator to carefully manage the sharing of data and 
system services, so it's very important to do the right thing and ask for foci whenever 
you need shared resources. 

PUTTING UP A MENU BAR 

One of the things that CClockPart does is to set up a menu bar. You can sec the code 
for this in CClockPart::Initialize, The initialization code gets a reference to its menu 
bar object and then calls the AddMenu method of the menu bar object to add its 
menus. Finally, it registers command IDs to pass back when menu items arc selected. 

OpenDoc provides a menu bar object to help you set up menus and display them 
when your part has obtained the menu focus. The major reason for diis object to exist 
at all is to support compatibility with Microsoft's proprietary' OLE 2.0 document 
architecture. This object hides die complex menu-mixing behavior of OLE 2.0 
behind a simple interface that works correctly in either an OpenDoc or an OLE 2.0 
container. 

Later, during execution of CFrame::FocusStateChanged, the menu bar object is asked 
to display itself. The actual code invoked is in CPart:: Install Men us, and basically just 
calls the Display method of the menu bar object. 

GETTING IDLE TIME 

You can get background time, delivered as idle events, on any of your frames. This is 
done by getting the dispatcher from the session object and registering particular 
frames for idle time, 
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You can see an example of this sort of registration in CClockPart::lnitialize. In this 
case, the part itself is registering to receive idle events, but individual frames can also 
be registered. Once a frame or part has been registered for idle time, it will receive 
idle events in its HandleEvent method. 

UNDO AND REDO 

Although CCIockPart is too simple to support undo, ids worthwhile to look at how 
you would go about adding undo support to your OpenDoc part handler. We’ve 
tried to make it as simple and unobtrusive as possible to do multilevel undo in 
OpenDoc. 

The first step is to create code that tells OpenDoc you’ve done something that can 
be undone. You do this by getting the undo object, an instance of XMPUndo, from 
the session object. You then call the XMPUndo::AddActionTbHistory method, 
which takes a hunk of data that you create to hold instructions about how to undo 
the latest action. OpenDoc never looks inside this hunk of hits; it merely stores it for 
later. 

The code might look like this: 

fSes sion~>GetUndo()->AddActionToHistory(thisPart, myUndoData, 
kXMPSingleAction, myUndoString, myRedoString) 

myUndoData is a pointer to the undo data, and myUndoString and myRedoString 
are strings to show in the Edit menu, to tell the user what action will be undone or 
redone. 

Once the information is on the undo stack, simply calling the XMPUndo::Undo and 
XMPUndo::Redo methods will cause the system to send the correct messages to the 
parts to get the last action undone. This allows the user to undo actions that were 
made in other parts, without your part knowing precisely w hat needs to be done. 

When the undo object is told to undo or redo, it calls your part handler back using 
the Undo or Redo method, Tfyou never post undo actions, you never need worry 
about having these methods called, and you can ignore them. The XMPUndo object 
will always return exactly w r hat you store in it, and it makes sure that undo and redo 
operations are invoked in the correct order. When the Undo object is finished with 
the undo data, it asks your part to dispose of it by calling your part’s Dispose Action State 
method. T his means that you can safely put pointers to other data into the undo data, 
since you’ll get a chance to dispose of the data, and anything it points to, at a later 
time. 

On some systems, such as one that supports persistent undo stacks, you may be asked 
to read and write your undo data against a persistent storage medium. This is not the 
case on die Macintosh, but OpenDoc does allow' lor it. You can safely ignore this 
until it becomes an issue on some platform you choose to support. 

STORAGE 

Eventually it becomes time to save a document. We’ve already discussed the OpenDoc 
storage environment to some degree. The storage unit object in Open Doe is set up 
for the part by the OpenDoc libraries themselves, so generally a part never needs to 
talk directly to die file system just to read and write its own data. This system 
supports not only compound document storage, but also a versioning system that 
a 11 ows for m u 1 ti p le drafts. 
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DEALING WITH STORAGE UNITS 

Once you’ve been given a storage unit, you typically get it ready by using the Focus 
call. To minimize the API, a set of common functions that can apply to the entire 
storage unit, a particular property, or a particular value has been abstracted out. 
Properties and values within a storage unit are not represented by distinct objects, but 
are instead captured in the focus state of the storage unit: the Focus method sets up 
the context for later calls. Fur example, the Remove method can apply to an entire 
property or to a single value of it, depending on whether the storage unit was focused 
on the property or on a value. Focusing can be absolute (when you pass a particular 
property ID or value index) or relative (when you pass a position code). 

The read operation is performed with the XMPSto ra geUnit:rGetValue method, and 
the write operation with XMPStorage Unit: :SetValue* The position can be set or 
read with XMPStorageUnit::SetOffeet and XMPStorageUnit::GetOffset. Efficient 
inserts and deletes can be performed with XA1 PS to rage Unit:: Insert Value and 
XMPStorageUnit:: Delete Value, You can also use the latter call to truncate a given value. 

Typically, your part will focus on the kXMPPropContents property and do various 
reads or writes, depending on w hether your pan is being internalized (read in from 
storage) or externalized (written out). If your part is sufficiently large and complex, 
you'll probably want to use inserts and deletes to store changes to your persistent 
data. This has two useful effects: it makes your data more randomly accessible, and it 
makes the OpenDoc draft system store changes more efficiently. 

This draft system allows a user to save a draft of a document and return to view the 
draft at any future time. Where possible, it stores only the changes between 
succeeding drafts, instead of storing entire copies of the document for each draft. By 
using Open Doc’s storage APIs, you automatically get this efficient storage of separate 
versions with no additional work on your part. OpenDoc only watches die storage 
operations, though; it doesn’t attempt to detect differences on its own. If you use 
insert arid delete operations, OpenDoc’s storage system can efficiently store the 
changes between drafts. 

BASIC I/O FOR YOUR PART 

When your part is brought into memory, your LnitPartFromStorage method is called, 
and it’s passed a storage unit. You are then responsible for reading the storage unit 
and getring ready to receive <nher messages. This w ill happen once, and never again 
until the object is deleted from memory. Later, when the document is being saved, 
your part's Externalize method is called. You must immediately write anything you 
need to store persistently out into your storage unit, before returning from this 
method. 

Your part is also free to write to its storage unit, as well as read from it, whenever it 
wants to. For part handlers that “virtualize 31 diemxelves from disk, this means that 
OpenDoc won't get in your way. 

The CCIoclcPart::IntemalizeContent and CClockPart::ExternalizeContent methods 
are called by the framework in response to the standard methods InitPartFromStorage 
and Externalize. They demonstrate focusing a storage unit and doing read and write 
operations. CQockParts storage needs are very simple; it just reads and writes a few 
flags into its storage unit* 

PART INFORMATION ATTACHED TO FRAMES 

As mentioned earlier, the XMPFrame objects associated with embedding have a 
partlnfo field, which is used like a window refCon by your code. When the document 
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is saved, you may he asked to save the contents of dais partlnfo field to a particular 
storage unit Your part will be called using the XMPPart:iWritePartlnfo method. 
Your responsibility is to write enough information to he able to reconstruct the 
partlnfo field. Later, when the document is reopened, your part object will he called 
with die XMPPart;; ReadPartlnfo method. This is your cue to read the data back into 
memory and set up the part info for rhat frame object once again. 

These partlnfo fields are useful when you want to write a part rhat can have several 
visible frames, each with a different presentation. The chart example we used earlier 
is a case in point. We would want to allow a chart to be viewed as a table of data or a 
chart, possibly one of various chart kinds. By storing information about what to 
display in the frame's part info, you're freed from writingyour own data structure to 
remember what kind of display to do in what frame. Instead, you store that 
information as a part of the frame’s part info and implement WritePartlnfo and 
ReadPardnlb methods to save and restore the data. 

CClockPart doesn't actually use the partlnfo field of its frames in a persistent fashion. 
It simply inherits code from CPart, which reconstructs the appropriate CFrame and 
CFacet objects at run time. This is completely adequate for simple parts. 

BEING A GOOD OPENDOC CITIZEN 

Now that we’ve covered the basics, there are a few last details to implement before 
we've got a good basic part. Since a part can have multiple frames, and a frame can be 
visible in multiple facets, we need to make sure our part handier does the right thing 
and avoids stepping on die toes of other parts. 

ADDING AND REMOVING FACETS 

When a part becomes visible {that is, when a facet appears), OpenDoc notifies the 
part with a call to the FacetAdded method. This is when your part should do any 
special setup it needs to (for instance, you may want to register lor idle time on the 
frame associated with that facet). Similarly, OpenDoc calls your part handler’s 
FacetRemoved method when the facet goes away; here you should clean up any 
actions you took in response to FacetAdded. 

ADJUSTING MENUS 

When your part handler acquires the menu locus, OpenDoc calls its AdjustMenus 
method. Your job is to correctly update the menus so that the right elements are 
checked, enabled, and so on. You can see an example in CClockPart: iDoAdjustMenus, 
which is called by die inherited code from CPart;:AdjustMenus. 

RELINQUISHING ARBITRATOR FOCI 

Once you've acquired any focus from the arbitrator, you'll eventually be called on to 
release it. This will happen via three methods: XMPPart::BeginRelinquishFocus, 
XMPPart: :CommitRelinquishFocus, and XMPPart::AbonRelinquishFocus. The first 
method is called to ask your part if it's willing to relinquish a focus it owns. It should, 
if at all possible, say yes. It’s possible, though, that you won't give up a focus, because 
your part object is in a mode. For instance, you wouldn’t give up the serial port focus 
if you were in die middle of an XMODEM transfer. 

Once your part has responded to the XMPPart::BeginReliiiquishFocus call, you 
can expect another call shordy after that which informs your part that the focus has 
really been given to another frame, or that it hasn't. The first case is signaled by 
XMPPart::CummitRelinquishFncus, and the second case is signaled by 
XMPPa rt:: Ahor tRelin q uishFocus. 
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Occasionally, under difficult conditions, your part will simply be informed that it has 
either acquired a focus (through the XMPPartuFocusAcquired method) or lost a 
focus (through the XMPPart::FocusLost method). If your part has lost a focus, you’re 
expected to avoid inappropriate behavior, such as attempting to adjust menus or 
display a menu bar when you don’t have the menu bar focus. 

FREEING MEMORY 

\bur part is expected, if possible, to free some memory on request. When it’s needed, 
you’ll l>e called with the XMPPart:: Purge method. You’re given a size that’s the 
amount of memory requested. If you can manage it, you should free any unneeded 
memory from your part s data structures. Don’t free anything you need to keep 
running, of course. You might free any resources you were holding, or free some 
cached data. CClockPart, our example, is so simple that it has almost nothing to 
purge. 

IN CLOSING 

By now you should have a good idea of what’s involved in writing an OpenDoc part 
handler. As you’ve seen, it’s much like writing an application today: you still write 
code to handle events, deal with storage issues, draw to the screen, and so on. The 
main differences are really in the “packaging” of the code and in the environment it 
runs in. (Some previously messy areas have even been cleanly abstracted for you. The 
storage system is a good example: no more ugly file handling code; you just deal with 
storage units and let OpenDoc handle the details.) 

But the differences for users are amazing. No more worry ing about which application 
can open which document. Instead, when they select a particular type of content to 
work with, the tools they need to work with that content simply appear. In user tests, 
many people thought that this radically wonderful technology was just a bug fix, and 
that it was finally working the way it was always supposed to. There can be no better 
indication that OpenDoc is a step in the right direction. 


Thanks to our technical reviewers David Austin, 
Ray Chiang, Mark Minshull, Alan Spragens, and 
Borek Vokach-Brad sky. * 
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DAVE EVANS 


BALANCE OF 
POWER 

Tuning PowerPC 
Memory Usage 


If you care about the performance of code you write for 
the Power Macintosh, memory usage should be your 
foremost concern* With the PowerPC™ 601 processor 
today, and even more important with future processors, 
memory usage of your code will have the greatest effect 
on its performance* Poorly written code will execute at 
a fraction of its potential, and often very simple 
changes will gready improve the execution speed of 
your critical code. 

Processors are improving much faster than the memory 
subsystems that support them. As the PowerPC chips 
move from 80 MHz to 100 MHz and beyond, their 
thirst for data to process and instructions to execute 
will increasingly tax memory. Memory caches attempt 
to midgate that thirst, and all PowerPC processors 
come equipped with built-in caches. But your code can 
work well with a cache or it can work very poorly with 
a cache. I'll show you why and discuss w hat yon can do 
to optimize your memory usage. 

CACHE BASICS 

As you know, a cache is simply very fast RAM that die 
processor can access quickly and that it uses to store 
recently referenced data and code. On the PowerPC 
processors, any data stored in the cache can be accessed 
without stalling the processor’s pipeline. Accesses to 
data not in the cache will take about 20 times as long 
reading from main memory, or even 1 million times as 
long if the access causes a page fault with virtual 
memory. Getting and keeping your performance- 
critical code and data in the cache are therefore key to 
your execution speed. 

A cache is divided into small blocks called cache lines , 

On the PowerPC 601, for example, the cache has 1024 


cache line blocks, each holding 32 bytes. In addition, 
the 601 will fetch two blocks when it can, making the 
cache line size effectively 64 bytes* 

The first PowerPC processors have set associative 
caches of different sizes. The 601 has an eight-Avay set 
associative, unified cache that’s 32K in size, and the 603 
has a two-way set associative, split cache with 8K for 
data and 8K for instruction code. The term set 
associative refers to the way the cache relates to main 
memory, which is important to your performance. In 
some simple caching schemes, each cache line maps 
directly to specific areas of main memory- any access to 
one of these areas loads bytes into that cache line. But 
on the PowerPC processor, sets of cache lines are 
combined and then mapped to memory. There are 
eight cache lines in each set on the 601, and two in 
each set on the 603* An access to one of the areas 
mapped to a set will load bytes into the last-used cache 
line of the set, keeping the most frequently used cache 
lines from being purged. This more complicated 
scheme typically yields much better performance than 
the directly mapped cache* 

CACHE THRASHING 

The cache will most affect your performance when 
you’re accessing large amounts of data. A typical 
example of this is walking through arrays to perform 
some operation. The best strategy is to minimize cache 
collisions during your accesses, and the best tactic for 
this is to access your data as sequentially as possible. If 
you walk through memory sequentially, you’ll load the 
cache every 64 bytes, but all 64 bytes wall be available 
for fast processing. Here’s an example: 

unsigned long data[64][1024 ] ; 
for (row = 2; row < 64; row++) 

for (column = 0; column < 1024; column++) 
data[row][column! s data[row-1][columnj + 
data[row-2][column]; 

This example performs additions on each dement of a 
large matrix and accesses that matrix sequentially in 
memory. It walks across each row, adding elements and 
storing the result. But just inverting the loops can 
significantly change the way memory is accessed: 

unsigned long data[64][1024]; 

for (column = 0; column < 1024; column++) 
for (row = 2; row < 64; row++) 

data[row][column] = datafrow-1][column] + 
data[row-2][column]; 


DAVE EVANS occasionally uses the combinatorics skills he gym. Designing last algorithms for Apple's OS Platforms Group is 

learned at the Massachusetts Institute of Technology, but more often definitely reward!ng, but developing a fast left hook really gets him 

he's been practicing his combination punches at □ Thai kickboxing pumped up.* 
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Reversing the loops leads to less than optimal 
performance since we perform each addition for all the 
columns before moving to the next element of a row. 
Instead of sequential access, this access pattern jumps 
across memory in even steps of 4K. Unfortunately, on 
the PowerPC processor these accesses map to the same 
set of cache lines, and every operation causes the cache 
to reload from main memory. This second example 
takes twice as long to execute the same calculation on a 
Power Macintosh 6100/60. 

By paying attention to how your code accesses memory, 
you can avoid serious cache thrashing like that done by 
the second example. Things to look out for are loops 
that iterate for a power of 2 steps (128, 256, and so on) 
and code whose memory accesses are not dose together. 

An approach called blocking may help your loops. Often 
your code isn’t as simple as above, and your memory 
accesses aren’t regular during the loop. If you’re 
walking two different arrays with different increments 
through memory, it may be impossible to serialize your 
accesses. Blocking performs the calculations in blocks 
of rows and columns. Instead of iterating across all the 
columns and then proceeding to the next row, you 
<1 iv i d e th e d i men s i o n a! spa ce i n to b I o cks a n d ca S c u! a te 
one whole block at a time. In this next example, we 
calculate the multiplication of two matrices. 

long result[64][64 ], foo[64][128], bar[128][64]; 
for (row = 0; row < 64; row++) 

for (column = 0; column < 64; column++) { 
long sum = 0; 
for (i = 0; i < 128; i++) 

sum += foo[row][i] * barfi][column]; 
result[row][column] = sum; 

} 

As this algorithm walks through memory, it accesses 
result and foo sequentially, but bar is accessed in 256- 
byte steps. Accessing bar by jumping through memory 
causes cache misses, and sequential elements of bar are 
flushed from the cache before they’re needed. 

By performing this operation in small blocks, we can 
better use the cache. The key is to use all the elements 
of foo and bar that are in a cache line before moving 
on. One way to do this is to expand die loop and 
perform four operations in a single iteration: 

long result[64][64], foo[64][128] r bar[128][64]; 
for (row = 0; row < 64; row++) 

for (column = 0; column < 64; column += 4) { 
long suml « 0, sum2 = 0; 
long sum3 = 0, sum4 = 0; 
for (i = 0; i < 128; i++) { 


suml += foo[row][i] * bar[i][column]; 
sum2 += foo[row][i] * bar [i][column+1]; 
sum3 += foo[row][i] * bar[i][column+2]; 
sum4 += foo[row][i] * bar[i][column+3]; 

} 

result[row][column] = suml; 
result[row][column+1] = sum2; 
result[row][column+2] = sum3; 
result[row][column+3] = sum4; 

} 

This expanded loop calculates a block of four cells in 
each iteration. This executes faster because elements of 
bar arc read from the cache and don’t always cause 
cache misses as in the earlier example. Notice that in 
the expanded inner loop, a cache line of the bar matrix 
will be loaded the first time that it’s referenced; then 
the following three references to bar will occur without 
stalling. Using the bar elements while they’re still in 
the cache gives us a significant improvement. 

CODE STYLE 

Good compilers can pay attention to your memory 
accesses and will optimize how you access memory. For 
example, load and store operations can he reordered by 
the compiler to occur when the data is most likely to he 
available. The first time data is accessed it tends to 
cause a cache line to load, and subsequent accesses to 
nearby data must also wait for the cache load to 
complete. The compiler may be able to help by 
inserting a few instructions between the loads. This 
way the cache line will be fully loaded when the 
subsequent accesses are needed. 

For more information on loop expansion and instruction 
reordering, see the Balance of Power column in develop Issue 18.* 

You can help your compiler by using local variables 
when you can. These tell the compiler exactly how the 
data will be used, enabling it to easily reorder the loads 
and stores for this data. 

You should also carefully note memory dereferences, 
especially double dereferences. Although it may be 
obvious to you, the compiler often can’t tell whether 
two pointers address the same object in memory. The 
compiler may be prevented from reordering 
instructions because it can’t tell whether two operations 
are really dependent on each other, just because they 
contain dereferences. Here’s an example: 

paramBlack->size = nvyStructure->size; 
paramBlock->offset = myStructure->offset; 

Although it appears obvious, the compiler usually can’t 
tell if pa ram Block references the same memory as 
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myStructure. In the resulting binary, the compiler will 
be conservative and not reorder these operations for 
best execution. Replacing the dereference of 
my S tr u ct it re w i th 1 oca I v a ri a b I es for si ze a nd off sc t wi 11 
allow the compiler to fully optimize this example. 

INSTRUCTION THRASHING 

Your code binary itself can cause the cache to thrash as 
it loads to be executed. This is very hard to detect and 
optimize. The basic problem is that your subroutines 
may map to the same areas of the cache, and frequent 
calls among them will stall to reload the cache. Some 
code profilers for RISC workstations have attempted to 
detect this problem, but for the Macintosh I can’t 
suggest much help, just changing the link order of your 
code and then executing profiles may have an effect; 
some link orders will thrash more than others. 

DATA STRUCTURES 

The layout of your data structures can greatly affect 
your cache usage and your memory usage in general. 
For example, memory accesses that cross 64-hit 
memory boundaries take twice as long to process, as 
this forces two bus transactions. On the PowerPC 601 


processor, any misaligned data access within a memory 
boundary takes the standard amount of time, which 
(b e canse o f typ i ca I M a c i n tos h d a cm s tru c t ti res) i s a 
valuable feature of the chip; future PowerPC 
processors, however, may take longer to access 
misaligned data. If you can align your data structures, 
do so now. A good tactic is to keep 64-bit data at the 
top of your structure, followed by your 3 2-bit data, and 
so on to prevent accidental misalignment of elements. 
Pad die end of the structure to an even 64-bit 
increment if you will have arrays of structures or will 
allocate th em on the stack. And if certain parts of your 
structure are accessed much more often than other 
parts, keep these together so that they stay in the cache, 
and make sure they’re aligned. 

DON'T FORGET 

The memory usage of your speed-critical code will 
gre a tl y a ffe e t i ts p e r fo r man ce tod ay, a n d c u r re n t 
problems will just get worse when PowerPC processors 
go above 100 MHz, Profile your code to find the most 
critical bottlenecks; then pay close attention to how 
that code addresses memory. You’ll be rewarded with 
an excellent return on your investment. 


Thanks to Tom Adams, Mike Coppella, Rob Johnston, and Mike 
Neil for reviewing this column.* 
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Designing 
Applications for 
the Power 
Macintosh 


The Power Macintosh offers surprises both for users 
and for developers. Users notice that its a fully 
compatible Macintosh and that native applications run 
blazing!y hist. Developers, upon learning how the 
Power Macintosh differs from a 680x0“based 
Macintosh, discover that its still basically a Macintosh. 
But the Power Macintosh can offer a much richer 
experience than was possible with previous computers 
if developers break free of their old assumptions and 
harness die power of the machine to make software not 
just (aster, but easier and more enjoyable to use. 

The Graphing Calculator desk accessory that ships 
with die Power Macintosh was designed to take 
advantage of the machine's power to make some 
ch a 11 en gi ng math cm a idea 1 tasks easi ly a cces sible —i n 
particular, algebraic manipulation and 2T) and 3-D 
graphing. In this column we'll share some lessons we 
learned when writing the Graphing Calculator. Well 
speak about software design rather than programming 
details because we frequently discovered that our 
intuition and the standard approaches to many aspects 
of the application design were no longer appropriate. 

In general, wc learned that ids time to break free of the 
idioms developed for the machines of 1984 ami begin 
design ing a n ew genera ti on of softwa re. W p Vr not in 
Kansas anymore. The lowest common denominator of 
hardware — where developers usually aim in order to 
m a i n tain co n si si e n cy a c ross all M ad n tos h i n o d el s — 
has changed. The target has typically been an 8 MHz 
68000 processor or, for color applications, perhaps a 
machine twice as fast. The lowest common 



GREG ROBBINS AND 
RON AVITZUR 


denominator for Apple's RISC-based line of machines 
is a 60 MHz PowerPC 601 processor. This change 
represents an enormous jump: on some floating-point 
operations, for example, the Power Macintosh is as 
much as 20,000 times faster. 

In our tests, calculations using the PowerPC processor's single- 
precisiort floating-point multiply-add instruction were 20,000 times 
faster. This means that if we had started a lengthy floatingpoint 
calculation in 1 984 at the release of the Macintosh, and that 
calculation were still being worked on by the computer, it would 
take a Power Macintosh starting now just four hours to catch up. * 

Even for developers targeting 680x0-based machines, a 
new approach to software design can dramatically 
improve users 1 experiences. The goal is to maximize 
use of whatever processing power is available in the 
design of the user interface. 

Here's a summary of the tips we'd like to pass on; we'll 
look at each one in more detail below. 

1. lackle expensive computations when they can 
improve the interface. 

2. Eliminate dialogs and command lines in favor of 
direct manipulation. 

3. Drop old assumptions and idioms. Use the 
processing power to explore new interfaces. 

4. Pr ovidea sta rti ng po i n t for exp I ora ti on. 

5. Avoid programming cleverness. Instead, assume a 
good compiler and write readable code. 

6. Invest development time in user-centered design. 

7. Learn the new rules for performance. 

8. Design tiered functionality: take advantage of 
whatever hardware you're running on. 

9. Test on real users. 

THE TIPS IN DETAIL 

1. Tackle expensive computations when they can 
improve the interface* 

We took a fresh look at how to implement the visual 
feedback for dragging, scrolling, and zooming. 
Traditionally, the Macintosh has represented these with 


GREG ROBBINS began writing educational software on the 
Apple II as a high school student Since then, he's picked up 
computer engineering degrees from U.C. Son Diego and the 
University of Pennsylvania, bagged wild boar in Fiji, and evaded 
sharks off Australia. When he's not consulting on Macintosh 
development, Greg gets way off the beaten track as a member of 
the Bay Area Mountain Rescue Unit.* 


RON AVITZUR considered working on the Graphing Calculator 
to be an exercise in single-minded obsessive behavior — good 
training for graduate school in physics. Ran has been writing 
educational math software since the dawn of the Macintosh. You 
haven't really seen the Graphing Calculator until Ron has shown it 
to you; in fact, Stewart Alsop's PC Letter names Ron one of the first 
Demo Gods. * 
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XOR animation, which gives the impression of the 
a c t i on w i th o u i re a 11 y rec a I culad rig the w i n d ow 
contents. This is how we first implemented them in the 
Gra ph i i ig Ca 1c u l a tor a s we 11; re d ra win g a n a 1 ge b ra i c 
equation or 2-D curve, not to mention a 3-D rendered 
surface, is computationally expensive. 

But to try to stress the processor, we tested the direct 
approach, and we found that the PowerPC processor 
could easily keep up* So now in the Calculator, when 
the user drags the axes, not only is the image dragged 
live but the exposed parts of the function are calculated 
and drawn as the mouse is moved. When the zoom 
buttons are clicked, the entire function is recomputed 
and redrawn several times to animate the zoom. In this 
way, applications can take advantage of the PowerPC] 
processor to dramatically improve the quality of 
interaction in ways that are not possible on slower 
machines. 

2. Eliminate din logs and command lines in favor of 
direct manipulation. 

Since there’s processing power to burn in the PowerPC 
601, we simplified the user interface by replacing many 
dialogs with direct manipulation. The Graphing 
Calculator doesn't have the dialogs typical of graphing 
programs for specifying the range and precision of a 
graph (x min , y mitl , y max , number of [joints, and so 
on). Instead, the user controls the view of a graph 
through direct manipulation. 

Today’s computers are fast enough to allow you to 
implement direct interaction for complex tasks. Certain 
time constants play crucial roles in human factors 
analysis. Recognizing these thresholds can help create a 
smoother interface. Tf a task like interacting with an 
equation takes under one-tenth of a second, users 
won’t be bothered by the delay; if it takes under one- 
fourth of a second, its fast enough not to he annoying. 
Longer delays, however, make users realize that they’re 
waiting. With fast response times, users can ignore 
the computer and have fun exploring the subject at 
hand. 

By emphasizing direct manipulation, we reduced even 
algebraic simplification, a task that might seem to 
require a command-line interface, to the paradigm of 
MacDraw. Math is traditionally intimidating, and math 
programs even more so, but we wanted to make 
mathematics fun. This w r as really a user-interface 
challenge, and it required rethinking many 
fundamental assumptions* Usability was our primary 
design goal; functionality was second. We were pleased 
to discover that with direct manipulation, we could 
simplify the interface without giving up powerful 
functionality. 


Since direct manipulation doesn’t require users to learn 
any new commands or concepts, the manipulations 
immediately become part of a user’s arsenal of tools. A 
powerful example of this is the drag algebra facility, 
which strikes many people as the most intriguing 
feature of the Calculator. The user can select a term of 
an equation and drag it elsew here in the equation, just 
like dragging an object in a drawing program. The 
Calculator performs the algebraic manipulations 
necessary to keep the equation consistent. This feature 
immediately boosts users into a realm where they can 
confidently and easily manipulate an equation. Just as 
simple calculators did with multiplication and division, 
it allows users w ho understand die essential concepts to 
immediately move on to more interesting problems. 

C Drop old assumptions and idioms. Use the 
processing power to explore new interfaces* 

On a Power Macintosh, you can handle hundreds or 
thousands of times more information than before 
interactively. This might allow rendered 3-D objects to 
become user-interface components, for example. While 
the Graphing Calculator flashes its buttons for the 
usual 8 ticks to indicate that they’ve been clicked, in 
that time it could compute and render a 3-D surface 
w r ith 1000 polygons. Imagine w hat controls might look 
like if they really taxed the processing power of the 
machine. 

Because functions are rendered so quickly on a Power 
Macintosh, we made 3-D surfaces spin by default. This 
gives users more information about the functions right 
away Furthermore, there are no menus or dialogs to 
control the view of surfaces; just as it does for 2-D 
graphs, the Calculator lets users change the 3-D view 
by grabbing the surface with the mouse. 

4. Provide a starting point for exploration . 

Applications should avoid batch setup operations, such 
as requiring users to set a lot of dialog options before 
performing an operation. Instead, provide a starting 
point for exploration, with reasonable defaults for 
whatever’s necessary to get users to that point. 

Perhaps the most unusual aspect of the Graphing 
Calculator is what it doesn’t ask of users. They don’t 
have to set up any graphing options before viewing a 
cu rve ora su r fa ce; t h e re a re n o p re I i m i n a ry d i a I ogs or 
required commands for users to do this. For any 
equation that can he graphed, die user simply clicks a 
Graph button to draw it. 

We ’ve all had the bew i Iderin g experienee o f tryi n g to 
use a program only to discover that we don’t even know 
how' to begin. One of the toughest problems is to 
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create an interface that makes functionality available 
and enjoyable for first-time users. But dearly this is 
where the design effort offers the greatest payoff 

5. Avoid programming cleverness. Instead , assume a 
good compiler and write readable code . 

Cycle-counting and compiler-specific optimizations are 
favorite pastimes of hackers, and sometimes they’re 
important. But we could never have completed the 
Graphing Calculator in under six months had we 
worried about optimizing each routine. Rather, we 
dealt with speed problems only when they were 
perceptible to users. 

We made no attempt to look at performance 
bottlenecks or at the compiled code of the Calculator 
iintil after running execution profiles. We were 
surprised where the time w as being spent. Most of the 
time that the Calculator is compute-bound it’s either in 
the madi libraries or in QuickDraw. So little time is 
spent in our code that even compiling it unoptimized 
didn’t slow it dow n perceptibly Improving our code’s 
performance meant calling the math libraries less often. 

Programmers are often tempted to spend time saving a 
tcw r bytes or cycles or to fine-tune an algorithm. If the 
change isn’t visible to users, however, the benefi ts may 
not extend beyond the programmer’s satisfaction. 

When most of the code in an application is 
straightforward and readable, maintenance and 
improvements are easier to make. Those are changes 
that users will notice. 

To maximize drawing speed without sacrificing compatibility, 
the Calculator renders its graphs offscreen in GWorlds and uses 
CopyBits to transfer them to the screen. See ''Drawing in GWorlds 
far Speed and Versatility" in develop Issue 10 for a discussion of 
this technique. * 

6, Invest development time in user-centered design . 

Complex algorithms should be used not for their own 
sake but to improve the user experience. For example, 
as the user drags the pane divider in the Calculator 
window, the application redraws most of the window 
(offscreen in a GWorld) rather than recalculating 
exposed areas. The PowerMacintosh is fast enough 
that it wasn’t worth spending coding and debugging 
time to save on runtime calculation, because the savings 
wouldn’t be perceived by the user. 

In contrast, when users click on a 2-D curve to read an 
(x,y) coordinate, some quite sophisticated processing 
happens. As the user moves the mouse, a numeric root- 
fi n d i n g a I go ri th m loo ks for i n teresti ng po in ts such a s 
maxima, minima, and zero-crossings to solve equations 


numerically. Furthermore, because numerical methods 
to find maxima and minima are imprecise, we also 
compute symbolic derivatives of the functions and then 
look for where the derivative is 0, which locates 
maxima and minima much more accurately. 

AH this w ork goes completely unnoticed by the user. 

But the user does notice the result: simply clicking on 
the curve tells with great precision what’s interesting at 
that point. 

7. Learn the new rules for performance * 

You may discover that there are places where 
performance tuning would be worthwhile in your 
application. The rules for performance have changed, 
and knowing the new rules is essential. Some 
programming techniques that traditionally improve 
performance can he counterproductive. In particular, 
on PowerPC-based systems, avoiding instruction cache 
misses is far more important than saving instructions. 

(retting good performance out of a fast machine 
doesn’t always come without effort. To he able to 
exploit modem hardware to improve an application, 
you must have some understanding of the hardware 
and what allows it to he fast. It’s extremely important to 
understand the processor and memory architecture of 
you r ta rge i pi a tinrm. 

The memory systern in the Power MacjnCosh is much 
faster than the memory system of other Macintosh 
models. The 64-bit bus allows for substantially 
improved data transfer. However, die processor is 
much, much faster than the memory system. An 
uncached memory reference may take 20 times as long 
as a cached memory reference. Performance will 
actua 11y be sIo wed down drama tically by a speed 
optimization t h a t sav es II oa ti 11 g- po in t m u l tiply 
instructions (expensive on some processors, but not on 
the PowerPC) at the expense of extra memory usage 
that forces instructions or data out of the cache. 

Understanding patterns of memory reference is very 
important in analyzing algorithms for performance. 
Stepping through an array across cache lines can 
quickly flush all lines out of the cache. (Cache lines are 
discussed in the Balance of Power column in this issue.) 
This can cripple attempts to walk the data structures 
typically maintained by interface-intensive applications. 
The PowerPC 601 has an eight-way set associative 
cache, which is fairly resilient to degradation from 
flushing of cache lines. However, the 603 processor has 
just a two-way set associative cache. Any processor- 
intensive calculations must avoid cache thrashing if 
they are to avoid degrading below an acceptable level of 
user responsiveness. 
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For additional architecture insights and tuning strategies, 
see the Balance of Power column in develop Issue 1 8 and in this 
issue,* 

Because no two platforms will run at the same speed, 
it’s important to design software to work well on a 
variety of machines. In principle, this means that the 
same application could run on any Macintosh, while 
being far more powerful — and more pleasant to use — 
on a Power JVE aci n tos h. 

S. Design tiered functionality: take advantage of 
whatever hardware you’re running on. 

just as iris frustrating for users of entry-level machines 
to he unable to run software, its equally frustrating for 
users of fast, high-end hardware with plenty of memory 
to have features execute unnecessarily slowly, or to be 
constrained by programs that expect and only take 
advantage of minimal resources. 

The Graphing Calculator does assume a Power 
Macintosh as its base platform; otherwise its 
expectations are modest. However, its appetite is 
unbounded. It does all drawing using offscreen buffers 
in teinporary men 1 ory \vhen a dequate RAM is avaliable, 
bu t will scale back to onscreen, QuickDraw-based 
rendering when temporary memory is limited. System 
7 makes this easy with purgeable GWorlds; once 
LockPixels fails, the Calculator know r s that it must 
work within tighter constraints. Later, when it can 
reallocate the offscreen buffer, it does so and resumes 
the fast, smooth graphing effects* When memory is 
abundant, the Calculator uses many temporary 
GWorlds to buffer frames ol 2-D inequality graphs 
calculated for varying values of n, such as the animation 

Of COS 77X < 0. 

The Graphing Calculator does all 2-D graph 
computation in 15-tick chunks. For simple curves, this 
typically renders the entire curve at once. But 2-D 
i n e qua 1 i ti es a re d ra wn p i ece 1 >y p i ece. O nce Power 
Macintosh computers are fast enough that an entire, 
complex inequality graph can be drawn in a single 15- 
ti ck ti m e s) i ce, use r s wi 11 b e a bl e to exp I or e i nequali des 
as fluidly as they can now play with simple functions, 

* I o ta ke a d va n ta ge o f Pas te r m a chines, a I way s base 
computational units on real time rather than on more 
arbitrary measures, Jf the Calculator had recomputed a 
fixed number of points and then called WaitNextEvent, 
too much time would have been yielded to other 
processes, even on graphs simple enough to be 


recomputed and drawn all at once. Instead, the 
Calculator calls TickCount and lets that dictate when it 
needs to yield time. This approach allows tor a smooth 
user interface anil cooperative execution regardless of 
the processor’s speed. 

Designing tiered functionality means abandoning 
assumptions about what is and is not practical on the 
target hardware. For addressing resources, such as 
available hardware and memory, or when execution can 
be threaded or time-sliced, the options are usually 
clear. For matters of raw speed, the proper approach 
may not be so obvious. It may come down to measuring 
the execution speed of a particular procedure at run 
time and basing a decision on that. For example, an 
animation effect might he suitable it it takes under 8 
ticks, or a routine that bypasses QuickDraw for 
drawing in a GWorld may be worthwhile if it really is 
faster than its QuickDraw alternative. 

For an example of timing graphics speed, see the article 
"Exploiting Graphics Speed on the Power Macintosh" in develop 
Issue 1 8,* 

9. Test on real users , 

The Grapiling Calculator reflects our vision of a new 
kind of calculator But user testing was essential for 
showing us the holes in our vision. For example, 
elements that were directly mani pul able in our eyes 
were overlooked by users. So we redesigned them to 
make their functions clearer, and then added a demo 
mode to point out important controls explicitly. 

In tests, the users who looked at the help pages 
invariably turned first to the page ar the end offering 
“tips,” This surprised us, hut also made clear where to 
put the most important information for using the 
Calculator. 

'Inward the end of the development of the Graphing 
Calculator, as the final user tests were being conducted, 
we saw students using the Calculator effectively within 
minutes, without instruction. Watching a high school 
student say “Wow!” as an equation came to life on the 
screen was probably the most satisfying moment for us 
as programmers. It was also the one that offered us the 
greatest hope about the future of personal computing. 
The Power Macintosh offers us the chance to reach 
more people while making the experience more 
enjoyable and easier for users than ever possible on 
earlier generations of computers. As developers, we 
have a new world to explore. 


Thanks to Arnaud Gourde!, Mike Neil, Don Norman, and Alex 
Rosenberg for reviewing rhis column.* 
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Adding QuickDraw GX Printing to QuickDraw 
Applications 


Now that QuickDraw GX has been released , you may be wondering 
what to do with your older QuickDraw applications. The good news is 
that by adding a relatively small percentage of code to your existing 
applications, you can support all the new features of the QuickDraw 
GX prin ting architecture and still retain full compatibility with 
non-QuickDraw GX systems. 



DAVE HERSEY 


Compatibility with the existing application base was a primary concern during the 
development of QuickDraw GX; only the most hardened u print criminals” should have 
compatibility problems. Since a pre-QuickDraw GX application should work in both 
QuickDraw GX and non—QuickDraw GX environments, you may think that leaving 
your code as it stands is good enough. Becoming compatible probably doesn’t require 
any revisions to your existing software, and the fact that your application will perform 
w i th nr wi thout Qui c kD raw G X sounds li k e a p re try go od d ea 1. Wh e re s the ca td i ? 

Here it is: A non-QuickDraw GX application doesn’t have access to several key 
features of QuickDraw GX, so its users can’t take advantage of many of the new 
printing features. For example, with QuickDraw GX a user can: 

* Redirect print jobs using the new Print dialog. 

* Choose page™by-page formatting, so that page 1 prints on US 
Letter, page 2 prints on #10 envelope, page 3 prints on landscape- 
oriented LIS Legal, and so on, instead of printing the entire 
document in a single format. 

* Work with the new QuickDraw GX printing dialogs (shown in 
Figure 1) instead oi the dialogs provided for compatibility with 
non-QuickDraw GX applications. 

* Use features provided by printing extensions. Printing extensions 
can add items to the QuickDraw GX printing dialogs, but not to 
the compatibility dialogs. (Added items show up as icons in the 
column on rhe left side of each dialog.) 

* Prin t a single copy of a document wi th the new Pri n t One Copy 
command. 

* Print documents by dragging them to desktop printers. 


DAVE HERSEY likes the annoying buzzing noise 
that JmageWrrters and ImogeWriter LQs make, 

He also en joys listening to Guns N Roses, but 
only while he's answering developer e-mail at 
Apple's Developer Support Center. Dave recently 
wrote a QuickDraw GX printer driver lor the 


Apple Color Plotter (which is from an era before 
the first Macintosh). When asked why be 
bothered, he said "Well, it makes this cool 
wacka-wacka sound." Clearly, Dave is an 
audiophile for the J 90s.* 
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Figure 1* The new QuickDraw GX printing dialogs 

Users are shut out from all these features if they’re using a non-QuickDraw GX 
application. In this article, you’ll see how to increase an application's level of 
QuickDraw GX support. HI take a QuickDraw application and convert it step by step 
into an application that fully supports both the QuickDraw and QuickDraw GX 
printing architectures. First, we’13 consider some definitions and background 
information. 

DIFFERENT LEVELS OF QUICKDRAW GX SUPPORT 

To begin, let’s define the different levels of QuickDraw GX support (from lowest to 
highest) that an application can have: 

* QuickDraw GX unaware: The application doesn’t implement any 
QuickDraw GX code, and QuickDraw GX translates all 
QuickDraw printing and drawing calls into QuickDraw GX 
equivalents. In other words, this is a non-QuickDraw GX 
application. 

* QuickDraw GX aware: The application implements a core set of 
QuickDraw GX printing features but retains compatibility with 
documents created with earlier versions. 

* QuickDraw GX savvy: The application implements full support for 
QuickDraw GX graphics, typography, and printing features. It 
also retains compatibility with documents created with earlier 
versions. 


QuickDraw GX dependent: The application requires the presence of 
QuickDraw GX graphics, typography, and printing routines to 
function. 
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Applications don’t need to implement any code to he QuickDraw GX unaware. 
Becoming QuickDraw GX aware requires some coding, hut typically not very much. 
Making your application QuickDraw GX aware is the minimal level of QuickDraw 
GX support that you should set your sights on — just follow the guidelines in this 
article. 

A QuickDraw GX-aware application is really a non-QuickDraw GX application at 
heart, with support for QuickDraw GX printing added. This application still uses its 
old QuickDraw commands to represent shapes and text; however, in its print loop, 
the application uses the QuickDraw GX graphics translator to translate QuickDraw 
commands into QuickDraw GX shapes for printing, if QuickDraw GX is available. 

If you’re just starling out on a new project, or you’re in the process of rewriting an 
existing product, you should consider the next level of compatibility: QuickDraw GX 
savvy. A QuickDraw GX-sawy application meets the requirements for being 
QuickDraw GX aware but also takes advantage of die extensive QuickDraw GX 
graphics and typography tools. You may feel that becoming QuickDraw GX savvy, 
although it brings widi it a wealth of increased capabilities, is too big a leap to take in 
the short term. In that case, consider making your existing applications QuickDraw 
GX aware and, once they’re released, going back and working on QuickDraw 
GX-sawy versions. 

A WORD ABOUT COMPATIBILITY 

Ids Apple’s hope and goal that no QuickDraw GX-unaware applications will be 
incompatible with QuickDraw GX. An existing application can he incompatible only 
if it relies on unsupported methods or on unpublished information that breaks under 
QuickDraw GX. For printing, this would include things such as trying to access the 
Printer Access Protocol (PAP) code from the ’PDEF' 10 resource of the LaserWriter 
driver. The QuickDraw GX LaserWriter driver doesn’t contain a PDEF 1 10 
resource, so applications that rely on this approach must be modified to work with 
QuickDraw GX. 

Developers were warned obout ihe disappearance of the 1 PDEF 1 10 resource in 
"Print Hints: Looking Ahead to QuickDraw GX 1 ' in develop Issue 13.* 

If your application has compatibility problems with QuickDraw GX, you probably 
already suspect it. You’re a candidate for such problems if you’re perpetrating any of 
the “printing crimes” or shaky methods that Apple has warned about in the past. 
Sweaty r palms and pangs of guilt whenever vour application is tested under new 
system soft ware are likely indications that you should get out your development tools 
and reform vour code now. (If you need the old code to run on non-QuickDraw GX 
systems, simply provide alternative code for running with QuickDraw GX.) Delve 
into the QuickDraw GX API — you’re sure to find a better way of doing things. 

SOME FUNDAMENTALS 

Before we go into the specifics of how to add QuickDraw GX printing to your 
existing applications, we need to cover some fundamental ideas. Fll start with a 
discussion of the Collection Manager, which makes its debut with QuickDraw GX, 
and then briefly cover overriding messages and the Message Manager. 

For a review of QuickDraw GX printing/ see "Getting Started With 
QuickDraw GX" and "Devefoping QuickDraw GX Printing Extensions/ both in 
develop Issue 1 5. See also Inside Macintosh: QuickDraw GX Printing * 


develop Issue 19 September 1994 


26 





CREATING A FOUNDATION TO BUILD ON: THE COLLECTION MANAGER 

The Collection Manager is somewhat like a memory-based version of the Resource 
Manager, It provides API calls that allow you to create and access collections, which are 
amorphous structures that can contain data ol different types with different sizes. 

(]ol I ecti ons are s i m i 1 a r to resou rce fi I es u nder th c R es t >u rce Mana ge r exce p 11 h a t 
collections must be in memory, while resource files are by definition disk based. 
Routines exist for “flattening” collections into a series of bytes that can he written to 
disk and for “unflattening” them for later use. 

Just as a resource file may contain Apple-defined data structures such as WIND' and 
MENU' resources, a collection may contain predefined collection items such as 
copy' anti ’rang 1 , which specify the number of copies of a print job and the page 
range of a print job, respectively. Like resources, collection items have attributes that 
are predefined (for example, the collectionLockMask attribute), hut unlike resources, 
they also have attributes that can be programmer defined. And, as with resources, you 
aren’t simply stuck with the core set that’s been defined by Apple. Figure 2 illustrates 
the similarities, including a programmer-defined resource of type ’USER' and a 
programmer-defined collection item, also of type ’USER'. 




Resource 

file 


Resource type: 'USER 1 

1 USER 1 | 


Resource ID: 128 

■WIND 1 


Resource attributes: 
locked 



'MENU * 


Variable-length data... 


Resources on hard disk 


Collection , 
’USER* 

f'copy' 


"rang 1 


Collection item type: 'USER' 


Collection item ID: 10 


Collection item attributes: 
col lection Loc kMa sk 

Variable-length data... 


Collection items in memory 


Figure 2* Similarities between resources and collection Items 


Items in a collection are uniquely identified in three different ways. Every item has a 
4-character label, or tag, which identifies the type of collection item. In Figure 2, 
there are three collection items having the tags j USER f , copy', and ’rang 1 , 
respectively In addition to the tag, every collection item has a longword ID. 

Together, the tag and ID are one way to uniquely identify a collection item. Each 
collection item can he also be referenced by its collection index or by its tag and tag 
list position. The index is the relative position of an item in a collection, and the tag list 
position is the relative position of a collection item within the item’s tag type — for 
example, the first, second, or third ’USER' item in a collection. This gives us three 
ways to refer to a specific collection item: 

* by its tag and ID 

* by its collection index 

* by its tag and tag list position 

It’s important to note that although a collection item’s index and tag list position may 
change as items are added or removed from a collection, an item’s tag and ID will 
never change. Therefore, the most common way to refer to collection items is by tag 
arid ID. 

Collection tog and resource type naming conventions are the same, Apple 
reserves tags listed in the printing interface files, as well as those consisting entirely of 
lowercase letters," 
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You can either create a collection with die NewCollection routine or use one of the 
three types of collections that QuickDraw GX automatically creates for you during 
printing. These types are job collections, format collections, and paper-type 
collections. Every time a new gxjob, gxFormat, or gxPaperType object is created, a 
collection is also created for that object. These collections contain items specifying 
the following types of information: 

* job collection: number of copies, page range, destination file 
information (if printing to a file) 

* format collection: scaling factor, page orientation, page flipping 
information 

* pap er- ty pc co 11 e cti on: pa pe r-typ e crea tor, pa pe r- typ e eo mrne n t 

These predefined collections contain many more collection items than are shown 
here* See the QuickDraw CX interface file PrintingManager.h for the complete 
listing. By simply changing the contents of the collection items, any application, 
printing extension, or printer driver can easily affect how a document will be printed* 

Note that all predefined collection items have the ID gxPrintmgTaglD - 
“ 28672 / 

Your application can create and use collections for its own purposes* By no means arc 
you restricted to using collections only within the QuickDraw GX printing 
architecture, although that’s probably where youII use them die most. 

OVERRIDING MESSAGES FROM AN APPLICATION: THE MESSAGE MANAGER 

Sam Weiss’s article in develop Issue 15,“Dcveloping QuickDraw GX Printing 
Extensions,” introduced the Message Manager* The QuickDraw GX printing 
architecture uses the Message Manager to invoke printing operations, and your 
application, printing extension, or printer driver can override messages to change 
printing behavior. This process is explained in Sam’s article, which is a good reference 
for anyone unfamiliar with the Message Manager and how r QuickDraw GX uses it. 
This article assumes that you already have at least a passing familiarity with the basic 
concepts. 

When you override a message from an application, you’re more restricted in w hat 
you can do than if you override a message from a printing extension or printer driver. 
To understand why, consider a case w here you want to override the QuickDraw GX 
printing message GXDespoolPage to add a serial number to the page before it’s 
printed* You can add this override to a printing extension in a straightforward w r ay 
that works regardless of which application prints the document* If, on the other hand, 
the override is attempted by an application, the situation becomes more problematic. 
The override won't be invoked because it’s a despooling-phase message; only 
application-phase and spooling-phase messages can be overridden by applications* 

To understand a second limitation of application overrides, let’s look at how they’re 
installed in the message handler chain. This is done by passing the routine 
GXlnstallApplicationOverride a pointer to the override procedure and a reference 
to the document’s job, like so: 

GXlnstallApplicationOverride(docJob, gxJobPrintDialog, 

MyJobPrintDialogOverride) - f 

In this example, the application is overriding the GXJohPrintDialog message with an 
override function called MyJobPrintDialogOverride. docJob is the gxjoh object for a 
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document. Because your application has access only to its own gxjob objects, an 
application override can be invoked only for the application that installed it. On the 
other hand, a message override from a printing extension can affect every document 
that’s printed, regardless of which application printed it. 

In summary: 

* Application overrides are reliable only during the application and 
spooling phases of printing, w r hich end once the document has 
been spooled to a print file. You should attempt to override only 
application-phase and spooling-phase messages from an 
application, 

* Application overrides are invoked only for the application 
installing the override, and only for the gxjob objects in which the 
overrides are installed. 

Application overrides are best suited for adding features to the printing dialogs and 
modifying the print file as a document is being spooled. If you feel limited by either 
of the conditions mentioned above, you should move your override out of your 
application anti into a printing extension. 

BECOMING AWARE 

Now let’s look at what an application developer needs to do to support QuickDraw 
GX printing. We’ll take a QuickDraw application called Simple Sample and convert 
it into its QuickDraw GX-aware counterpart, Simple Sample GX. The code for both 
samples is on this issue’s CD, 

The Simple Sample application draws using various QuickDraw commands, 
including those for simple objects, bitmaps, and PicComments. It can handle 
multiple documents with multiple pages, and although it knows nothing about 
QuickDraw GX, it is System 7 dependent {I made it that way to save on code and 
confusion). 

Here’s a summary of what most QuickDraw GX-aware applications need to do: 

* Determine whether QuickDraw GX is present, anti if so, initialize 
the QuickDraw GX managers (and close them down when the 
application quits). 

* Create a gxjob object for each document created anti dispose of 
the gxjob when die document is closed. 

* Override the GXPrintmgEvent message (in order to support the 
QuickDraw GX movable modal printing dialogs) while printing 
dialogs are displayed. 

* Update gxjob objects on resume events (in case the characteristics 
of the desktop printer you’re printing to have changed). 

* Save and load a document’s gxjob object to and from disk and 
convert print records to gxjob objects when loading documents 
created from pre-QuickDraw GX versions of your application . 

* Alake the Custom Page Setup and Print One Copy menu items 
available in the File menu. 

* Invoke the QuickDraw GX printing dialogs and support custom 
formatting by page (each page can have a unique page format, or 
can share another page’s format). 
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* Store page-to-format correspondences to disk with a document 
(and load them again when the document is opened)* 

* Have a print loop that uses QuickDraw GX printing commands 
and translates QuickDraw commands to QuickDraw GX shapes 
for printing, 

* Implement the Print One Copy feature. 

* Support the new attribute of the 'pdoc' Apple event to properly 
support drag-and-drop printing of documents from the Finder* 

Each of these is discussed in order in the rest of this article. 

PREPARATION 

Before you can do anything with QuickDraw GX, you need to determine whether it’s 
available* You should do this in your initialize routine, after youVe determined that 
the other managers your application requires are available. The MylnitGXIfPresent 
routine in Listing l shows one way of doing this. 


Listing 1* QuickDraw GX preparation and cleanup 

void MylnitGXIfPresent() 
t 

long gxVersion, gxPrintVersion; 

gGXIsPresent - false; 

/* Check to see whether QuickDraw GX is available. */ 
if (Gestalt[gestaltGXVersion, &gxVersion) = noErr) 

if (Gestalt(gestaltGXPrintingMgrVersion, &gxPrintVersion) 
noErr) 

gGXIsPresent = true; 

/* If so, initialize QuickDraw GX. */ 
if (gGXIsPresent) { 

gClient = GXNewGraphicsClient(nil, kGraphicsHeapSize, 

(gxClientAttribute) 0); 

GXEnterGraphics(); 

GXInitPrinting{); 

> 

1 

void MyCleanUpGXIfPresent() 

1 

if (gGXIsPresent) { 

GXExitPrinting(); 

GXDisposeGraphicsClient{gClient}; 

GXSxitGraphics(); 

} 

} 


In MylnitGXIfPresent, we use Gestalt to determine whether the QuickDraw GX 
graphics and printing routines are present. If so, we call GXNewGraphicsCUent 
to set aside memory for QuickDraw GX graphics operations, and we call 
GXEnterGraphics and GXlnitPrinting to enable the QuickDraw' GX functions well 


30 


develop l&sue 19 September 1994 







use. Note that we also set a global variable, gGXIsPresent, which indicates whether 
the QuickDraw GX managers we require are present. We'll check this value 
whenever we need to make a decision about whether to use QuickDraw or 
QuickDraw GX methods. 

Important: You cannot intermix Printing Manager and QuickDraw GX printing calls. 
Do not call _PrGlue[A8FD] if you have called _InitPrinting. 

When the user quits the application, we need to release any memory we allocated and 
close down QuickDraw GX printing and graphics. We do this as shown in the 
MyCleanUpGXIfPresent routine in Listing 1. 

CREATING AND DISPOSING OF GXJOB OBJECTS 

With the MylnitGXIfPresent and MyCleanUpGXIfPresent routines added to our 
code, we’re now ready to make our application’s documents fit into die QuickDraw 
GX print model. We do this by creating a gxjob object whenever we create a 
document. Our non-QuickDraw GX application. Simple Sample, contains a routine 
named MyCreateDocument that’s called whenever the user creates a document. As 
shown in the Simple Sample GX application, this routine is modified so that when 
QuickDraw GX is present (as indicated by the gGXIsPresent global variable), the 
application creates a gxjob for each document, using die GXNewJob routine. If 
QuickDraw GX is not present, die application creates a print record handle 
(TII Print) instead. 

It’s common for an application to store descriptive information about a document in a 
private data structure, and our sample is no exception. The application uses a private 
structure called MyDocumentRec that contains information about the number of 
pages in a document, the current page being viewed, and so forth. We modify this 
structure also, so that we can store a document’s job reference and page formatting 
information with the document. As seen in Listing 2, weVe added the document]ob 
and pageFormat fields to the structure. The rest of the fields in this structure were 
already being managed by the QuickDraw GX-unaware application, and we’ll 
continue to use them. 


Listing MyDocumenlRec, modified for QuickDraw GX 

fdefine kMaxPages 20 /* Max 

pages the sample handles. */ 

typedef struct MyDocumentRec { 


THPrint 

documentPrintHdl; /* Print record for document. */ 

gxJob 

documentJob; 

/* Job for document. */ 

gxFormat 

pageFormat[kMaxPages]; /* Format for each page* */ 



/* If nil, we use the job format, */ 

long 

numPages; 

/* Number of pages in document. */ 

long 

curPage; 

/* The current page displayed. */ 

FSSpec 

docmnentFSSpec ; 

/* Document's file spec, */ 

Str31 

documentTitle; 

/* The title of this document, *7 

WindowPtr 

documentWindow ; 

/* The window for this document,*/ 

1 MyDocumentRec, 

*MyDocumentPtr; 



We also need to modify the application’s MyDisposeDocument routine, which is 
called whenever a document is closed. In the modified routine, we dispose of the 
document’s gxjob. 
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The changes that we’ve made so far are indicative of the approach we’ll continue to 
use as we make our sample QuickDraw GX aware: adding code that executes only if 
QuickDraw GX is present. If the aser isn’t running QuickDraw GX, our converted 
sample will appear and function as the original did. But if QuickDraw GX is present, 
all the new functionality will kick in. 

OVERRIDING GXPRINilNGEVENT 

When we added support for gxjobs in the MyCreateDocmiient routine, we also 
added the following line of code: 

GXInstallApplicationOverri.de((*createdDocument)->document Job, 

g xP rintingE ve nt, My P rintin gEven tover ride); 

Every application that aspires to be QuickDraw GX aware should include such a 
line. Remember, QuickDraw GX has movable modal printing dialogs; the 
GXPrmtmgEvent message is sent whenever a dialog is moved. Unless you override 
GXPrintingEvent, you won’t have a chance to update your application’s windows 
when the dialogs are moved. 

The code to support window updates when the printing dialogs are moved is actually 
quite simple. You just need to add a routine that overrides the GXPrinti ngE vent 
message and calls your event-handling routine (Listing 3), anti to make sure that 
you’ve disabled the appropriate menu items before displaying the new printing 
dialogs. Note that vour override should not forward the GXPrintingEvent message, 
but instead should perform a total override of it. 


Listing 3* MyPrinHngEventOverride 

OSErr MyPrintingEventQverride(EventRecord *anEvent r Boolean filterEvent) 

h Handle events in whatever way is appropriate. MyDoEvent is 
our generic event handler. We don't pass it events that it 
shouldn't handle while printing dialogs are displayed, */ 
if (IfliterEvent) 

switch (anEvent->what) { 
case mouseDown: 
case keyDown: 
case autoKey: 

break; 
default: 

MyDoEvent (anEvent); 
return noErr ; 

} 


UPDATING GXiOB OBJECTS ON RESUME EVENTS 

There’s another piece of event-handling code that every QuickDraw GX—aware 
application should include. To support the reentrant nature of QuickDraw GX, you 
must call GXUpdatejob on each gxjob that your application is using whenever you 
receive a resume event. (See the code for Simple Sample GX on the CD.) This 
enables QuickDraw GX to update the information in the gxjob in case it changed 
while your application was in the background. As an example, suppose that a user 
suspends your application to change the printing extension setup for the destination 
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desktop printer Upon switching back to your application, this user will expect any 
open documents to use these new settings at print time. Unless you call GXUpdateJob 
on your gxjob objects, the new settings won’t be there. 

SAVING AND LOADING A DOCUMENT S GXJOB 

Now that we can create gxjob objects for new documents, let’s take a took at how we 
can save these to disk and later retrieve them when the documents are opened. We 
want to save them for the same reason that we want to store print records with 
documents under non-QuickDraw GX systems: if a user has gone to die trouble of 
configuring print settings for a document, the user-friendly thing to do is to use those 
settings the next time the document is opened. 

Because the data we want to save is stored in an abstract data structure (gxjob), we 
need a way to convert it to a more tangible form. We accomplish this with the 
GXFlattepJob or GXFIattenJobToHdl routine. GXFlattenjob passes the converted 
data as a stream of bytes, whereas GXFIattenJobToHdl places the flattened data in a 
handle. You would typically use GXFlattenjob to store the flattened gxjob in a data 
fork, but GXFIattenJobToHdl to save it as a resource. 

Since our application stores its print records in resources, we’ll store its flattened 
gxjob objects in resources as well. To do this, we modify our application’s 
MySavePrintlnfo routine, which is called to save print records to disk. If QuickDraw 
GX is present, the routine will instead save our flattened gxjob. 

In the following code, we flatten a gxjob into a handle called thePrintData, which can 
then be wTitten to the disk as a resource. 

thePrintData = NevHandle(0); 

GXFIattenJobToHdl(whichDo eminent-> documentJob r thePrintData); 

Next, we modify die application’s MyLuadPrintlnfb routine, which is used to retrieve 
print records that were previously saved with xMySavePrintlnfo. This routine must do 
several things, based on whether QuickDraw r GX is present and whether a gxjob or 
print record has been previously stored with a document. The flow of control is 
shown in Listing 4. 


Listing 4- MyloadPnntlnfo Flow of control 

if (gGXIsPr e s ent) { 

if there's a previously saved gxJoh 
unflatten it and use it 
else 

if there's a previously saved print record 
convert that to a gxJob and use it 
else 

use the default gxJob we created in MyCreateDocument 

} 

else { 

if there's a previously saved print record 
use it 
else 

use the default print record we created in MyCreateDocument 
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As it turns out, some of the steps in Listing 4 can lie combined. For example, 
regardless of whether QuickDraw GX is present, we may need to retrieve a 
previously saved print record. What?! Accessing old-style print records when 
QuickDraw GX is present? Sounds strange, doesn’t it? We need to do this if 
QuickDraw GX is available and the user opens a document that contains a prim 
record but not a gxjob (because it was created with an older version of the 
application). We convert the print record to a gxjob with the GXConvertPrintRecord 
routine, so that the gxjob has as many of the old print record’s settings as possible. 

CONFIGURING AND HANDUNG MENUS 

We need to alter our menu routines so that the Custom Page Setup and Print One 
Copy commands are available to QuickDraw’ GX users. We might decide to have two 
different File menus, the installation of which would depend on whether QuickDraw 
GX is present. Or we might have only one File menu and add or subtract items from 
it when it’s installed in the menu bar. The approach that’s best for a particular 
application depends on how the application is structured. (The same choice of 
approaches applies to other menus that might need to be modified based on whether 
QuickDraw GX is available,) 

In the sample code, we modify the File menu as follows: the application contains a 
'MENU' resource for the QuickDraw GX version of the File menu; if gGXIsPresent 
is false, we remove the Print One Copy and Custom Page Setup menu items from 
this menu. 

fileMena = GetMHandle(mFile ); 

DelMenuItemffileMenu f iPrintOneCopy ); 

DelMenuItem(£i1eMe nu, iCu s tomPageSetup); 

The order of the deletions is very important! If we deleted in the reverse order, the 
Custom Page Setup menu item would be deleted, but when we tried to delete Print 
One Copy, we would actually delete w hatever came after Print One Copy. Why? 
Because the menu would be one item shorter, and the index into it would no longer 
be valid. Just delete menu items from bottom to top and you’ll be fine. 

Monkeying around with the placement (and inclusion) of menu items like this will 
throw our menu-enabling and menu-selection routines out of whack* We need to 
make sure that regardless of whether the Print command is item number 8 or 9 in the 
menu, we soil treat it as a Print command. Again, the approach to use will depend on 
the application. 

It’s conceivable that you would use macros and would make the same changes to both 
the menu-enabling and menu-selection routines, but in the sample I chose to tackle 
menu enabling and disabling differently than I did menu handling. For the simple 
enabling and disabling of menus in the MyAdjustMenus routine, I check to see 
whether QuickDraw GX is present and adjust the item numbers based on that. This 
is the easiest approach because it requires only minor changes to the routine. 

'The menu selection situation is a little different. Typically, applications contain a 
routine that uses a switch statement based on the ID of the menu and menu items 
chosen. This means that we’d need either two such routines (one for QuickDraw 
and one for QuickDraw GX) or a different approach from what we used in 
MyAdjustMenus. I opted for a different approach. 

The sample application’s MyDoMenuCommand routine uses a switch statement (as 
most applications do) based on the menu ID and menu item extracted from the result 
of the MenuSelect and MenuKey routines. When QuickDraw GX is not present, the 
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Quit menu item will be item 10 in the File menu; otherwise, it will be at item 12 (see 
Figure 3). The switch statement in the MyDoMenuCommand function compares the 
menu item selected to the items in the QuickDraw GX version of our File menu. 
Therefore, it will expect that item 12 will be Quit. Item 10 will be interpreted as 
Print One Copy! This would be disastrous — the application would not quit, and our 
QuickDraw GX-specific code would be executed when QuickDraw GX wasn’t 
around! That’s not likely to be a pleasant user experience. 
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38N 

Open... 
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Sane 
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Custom Page Setup... 
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Print One Copy 

Quit 96Q 


When QuickDraw GX is present 


Figure 3. The File menu without QuickDraw GX ond with QuickDraw GX 


A new routine, MyConvertMenuItetn, solves this problem (Listing 5). This routine is 
called just before we enrer the switch statement in MyDoMenuCommand. If 
QuickDraw GX is present, MyConvenMenuItem does nothing; otherwise, it checks 
to see if die menu item selected was affected by our deletion of the QuickDraw GX 
menu items, and if so adjusts it. How’s that for an easy solution? 


Listing 5. MyConvertMenultem 

void MyConvertMemiItem(short *meiruID, short * menu Item} 

{ 

if (IgGXIsPresent) { 

if (*memiltem = iCustomPageSetup) 

*memiltera = iPrint; /* Print was selected, */ 

else 

if (*menultem == iPrintOneCopy) 

*menultem = iQuit; / * Quit was selected. */ 

} 

} 


INVOKING THE PRINTING DIALOGS AND SUPPORTING CUSTOM 
FORMATTING 

Earlier, we added code to our application to support window updates when the 
printing dialogs are displayed. Now, let’s discuss the code required to actually display 
the dialogs. 

There are now three printing dialogs instead of two (as shown earlier in Figure 1). 
The Page Setup dialog now allows users to modify a document’s default page format. 
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The new dialog, Custom Page Setup, provides a way to change page formatting on a 
page-by-page basis. If your application creates documents that can have only a single 
page, implementing the Custom Page Setup dialog isn’t necessary; the Page Setup 
dialog can be used to configure the document’s only page format. The Print dialog is 
similar to its non-QuickDraw GX counterpart, although much enhanced. 

We use GXjobDefaultFormatDialog, GXFormatDialog, and GXJobPrintDialog to 
display the Page Setup, Custom Page Setup, and Print dialogs, respectively 

We modify our MyDoPageSetup routine to call GXJobDefaultEormatDialog instead 
of PrStlDialog when QuickDraw GX is present. In our MyDoCustomPageSetup 
routine, which is called only when QuickDraw GX is available, we simply call 
GXFormatDialog, passing the current page’s gxFormat. 

Ln both of these page setup routines, and in the code for MyPrintDocurnent that 
follows, we call a function named MyAdjustMenusForPrintDialogs, which disables 
and enables entire menus (Listing 6). We disable menus before displaying a printing 
dialog, and enable them once the dialog goes away. If we didn’t disable the menus, 
users w r ould he able to select menu items. And, because the GXPrintingEvent 
override calls our MyDoEvent routine, any qucucd-up menu selections would he 
processed when the GXPrintingEvent message was sent. The user could be in the 
Print dialog, then select Quit from the File menu, and the next time the window was 
updated, the application would quit! 'The only menus a user should have access to are 
the Edit menu and the system menus, (Users can open desk accessories from the 
Apple menu, for example, w f hile a printing dialog is displayed — but they should not 
be able to open the About item for the application,) 


Li sting 6. MyAdjusfMenusForPnnJ Dialogs 

void MyAdjustMenusForPrintDialogs(Boolean dialogGoingUp) 

{ 

MenuHandle appleMenu, fileMenu, editMenu, documentMenu; 

appleMenu = GetMHandlefmApple); 
fileMenu = GetKHandle(mFile); 
editMenu = GetMHandle(mEdit); 
documentMenu = GetMHandle(mDocumentJ; 

If (dialogGoingUp) { 

Disableltem(appleMenu t iAbout); 

Disableltem(fileMenu, 0)? 

Disableltem{documentMenu, 0); 

HiliteMemi( 0}; 

> 

else { 

Enableltem(appleMenu f iAbout)? 

EnableltemffileMenu, 0)? 

DisableItem(editMenu r 0); 

Enableltem(documentMenu, 0); 

> 

DrawMenuBar(); 

gInPrintDialog = dialogGoingUp; 
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The system enables some menus, namely the Help menu, the Application 
menu, and the Keyboard menu, even when dialogs are displayed. Your code doesn't 
need to deal with them," 

The MyPrintDocument routine (Listing 7) displays the appropriate Print dialog and 
then branches to our QuickDraw or QuickDraw GX printing routine. Note that 
weVe been careful to call PrOpen and PrClose only when QuickDraw GX is not 
present. As mentioned earlier, you cannot intermix Printing Manager and 
QuickDraw GX printing calls. 


Listing 7. MyPrinlDocLiment 

OSErr MyPrintDocuiQent(MyDocmnentPtr whichDocument) 

{ 

OSErr err = noErr; 

gxEditMenuRecor d editMenuRe c; 
gxDialogftesult result; 

if {gGXIsPresent) { 

f* If GX is present, fill in the location of the application's 
Edit menu items, enable/disable the appropriate menu items, 
and display the Print dialog. If the user clicks OK, print. */ 
editMenuHec.editMenuID = mEdit; 
editMenuHec.cutItem = iCut; 
editMenuRec.copyltem = iCopy; 
editHenuRec.pasteltem = iPaste; 
editHenuRec,clearItem - iClear; 
editHenuRec.undoItem “ iUndo; 

MyAdjustMenusForPrintDialogs(true); 
result = GX JobPrint Dialog {whichDoeument~>docuirierit Job, 
seditMenuRec); 

MyAdjustMenusForPrintDialogs(false); 
if (result == gxOKSelected) 

err = MyGXP rintLoop(whic h D oc ume nt); 

} 

else { 

/* If GX is NOT present, open the printer driver and print 
using the Printing Manager. */ 

PrOpen{); 

if (PrJobDialog{whichDocument->documentPrintHdl)) 
err = MyQDPrintLoop(whichDocument); 

PrClose(); 

> 

return err; 


WeVe made a few other changes behind the scenes; see the complete code on the 
CD for details. The code for repaginating a document has been changed slightly to 
use the dimensions of QuickDraw GX page formats, if available, rather than those 
in the rPage field of the old print record. We also made minor changes to our 
MylnsertPage and MyDisposePage routines in order to manage gxFormats on a 
page-by-page basis. In the Simple Sample GX application, we store nil in our 
MyDocumcntRec.pageFormat array whenever a new page is created. Because nil is 
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an invalid gxFormat reference, we can use it to tell the application to use our gxjob 
object's default format for a given page. If the value stored is non-nil, we can safely 
assume that it's a valid reference to a custom page format. Finally, in our 
MyDisposePage routine, we now call GXDispose Format if the page being removed 
uses a custom page format. 

Since we store gxFormat references on a page-by-page basis, shouldn't we also 
dispose of page formats in the MyDisposeDociunent routine? Well, we certainly can 
do that, but there’s really no need. When we dispose of the document’s gxjob, 
QuickDraw GX automatically disposes of all of the job’s page formats. The flip side 
of this is that you must not attempt to use any gxFormat references once die format’s 
corresponding job is disposed of. 

Continuing with this line of thought, what happens to a document’s page formats 
when the document is saved to disk and later reopened? As it turns out, flattening a 
gxjob causes all of the job’s page formats to be flattened also. This means that the 
code we wrote earlier to flatten and store a document's gxjob in a resource will also 
store page formats. When we later unflatten the job, the page formats will be 
unflattened as well. 

STORING THE PAGE-TO-FORMAT CORRESPONDENCES 

It’s easy to fall into the trap of thinking that you don’t need to do anything more to 
support saving and loading of by-page formats — hut don’t. There are still two more 
issues to consider. 

The first issue is straightforward enough: we haven’t stored our page-to-fonnat 
correspondences, so the next lime w r e open the document we’ll have no idea which 
format goes with which page. The second issue requires a bit more explaining. 

When QuickDraw GX creates a page format, it returns a format reference that’s 
based partially on the reference of the job with which the format ts associated. Since 
reference IDs for gxjob objects differ depending on conditions when the job is 
created, a job reference that’s valid when a document is saved is unlikely to be correct 
w r hen the document is later reopened. Similarly, the format references we have when 
a document is saved are unlikely to be correct when the document’s job is later 
un flattened. 

It should now be clear that we can’t simply store our page format reference IDs with 
a document, lo provide the page-to-format information we’ll need w hen we open the 
document, we have to find another method. Fortunately, there’s a very easy way to do 
this via the Collection Manager 

As mentioned earlier, every gxFormat has a collection associated with it. QuickDraw r 
GX creates these collections automatically when a gxFormat is created. When a 
format is flattened, its collection is also flattened. Specifically, any collection items 
that have the collectionPersistenccBit attribute set are included in the flattened data 
stream. This attribute is set by default when a new collection item is added, so you 
need to change it only if you don't want a collection item to he included in the 
flattened data. 

To store page-to-format mapping, we’ll create a custom collection item. We’ll store 
this collection item in the default format’s format collection. The collection item 
consists of an array oflong words — one for each page in the document. In this 
array, we store the index of the format to use for each page, in order. Since format 
indices are preserved during flattening (unlike format references\ we’ll be able to 
reconstruct the page-to-fonnat relationships when we reopen the document. The 
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MySaveFormatRefe routine (Listing 8) saves the format indices. This routine is called 
from our MySavePrintlnfo routine, just before we flatten the document’s gxjob (and 
in turn its page formats and format collections). 


Listing 8. MySaveFormatRefs 

♦define kMyFormatlnfoType ■FLST■ 

♦define kMyFormatlnfoTaglD IQ 00 

OSErr MySaveFormatRefs(MyDocument?tr whichDocument) 

{ 

OSErr err = noErr; 

Handle theFormatldxLis t; 

Collection fmtCollection; 

gxFormat defaultFmt; 

if (whichDocument->numPages >0) { 

/* Get the job's default format's collection. */ 

defaultFmt = GXGetJobFormat(whichDocument->docuinentJob, 1); 

fmtCollection - GXGetFormateollection(defau1tFmt); 

/* Create a list of page-to-format correspondences for the 
current document. If there are no errors, add the item to 
the job's default format's collection for later retrieval. */ 
err = MyCreateFormatlndexList(whichDocument, &theFormatldxListJ; 
if (err = noErr) { 

0Lock:( theFormatldxList ); 

err = AddCoXlectionItem(fmtCollection, kMyFormatlnfoType, 

kMyFormatlnfoTaglD, GetHandleSize(theFormatldxList ) f 
*theFormatldxL1st); 

Dispose Hand1e(theFormatIdxLis t ); 

} 

} 

return err; 

} 


Our saved documents now contain information for associating pages with page 
formats. The MyAdjustFormats routine (Listing 9) extracts this information from the 
default format’s format collection when we load the saved document In effect, the 
code finds new format reference IDs for each format we flattened and stores those 
IDs with the pages that use them. In this way, we completely avoid relying on the old 
(and invalid) format references. 

TRANSLATING AND PRINTING QUICKDRAW COMMANDS 

At long last, we’re ready to look at the code that translates our QuickDraw 
commands to QuickDraw GX shapes and prints them. 

To do the translation, well use the QuickDraw GX translator routines. We specify 
how we would like the translation to be performed by passing one of the 
gxTransIationOptions to the translator routines. (The routines and translation 
options are listed in Inside Macintosh: QuickDraw GX Environment and Utilities.) 
Normally, die default translation options are all you need, and those are w hat we use 
in Simple Sample GX. 
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Listing 9. MyAdjustFormats 


GSEr r My Ad j u stFo rmat s (My Doc uinentPt r wh i c hDo c rnnent) 


{ 


OSErr 

Handle 

gxFormat 

long 

Collection 


err = noErr; 
theFormatldxList = nil; 
theFormat, def aultFmt ; 

pg, numPages, fmtldx, *idxList J idx, llstSize, 
fmtCollection; 


attribs; 


defaultFmt = GXGetJobFormat(whichDocument->documentJob, 1); 
fmtCollection = GXGetFormatCollection(defaultFmt); 
err = GetCollectionltemlnfoffmtCollection, kMyFormatlnfoType r 
kMyFormatljtfoTagID , sidx, slistsize, sattribs); 
if (err == noErr) 

theFormatldxList = NewHandle(listSize); 
if (theFormatldxList 1= nil) { 

HLock{theFormatldxList); 

err s GetCollectionI tern (fmtCollection, kiMyFormatlnfo'fype, 

kMyFormatInfoTagID, dontWantSize, *theFormatldxList}; 
numPages = listSize / sizeof(long); 
idxList = (long *) ^theFormatldxList; 
for (pg = 0; (err == noErr) && (pg < numPages); pg++) { 
fmtldx » idxList[pg]; 
if (fmtldx 1« (long) nil) { 

theFormat = GXGetJobFomat(whichDocument-^document Job, 

fmtldx); 

err = GXGetJobError(whichDocument->documentJob); 

} 

else 

theFormat = nil; 
if (err == noErr) 

whichDocument->pageFormat[pgj = theFormat; 

} 

QisposeHandle(theFormatldxList); 

} 

return err; 


The translation routines come in two varieties — those that take a single QuickDraw 
PicHandle and convert it to a QuickDraw GX picture shape, and those that let you 
execute QuickDraw commands and create equivalent QuickDraw GX shapes as you 
do so. Converting a PicHandle to a gxPicture shape is straightforward; therefore, 
we’re going to take the second approach. Most applications don’t print by simply 
making a QuickDraw Draw Picture call, so understanding how to convert individual 
QuickDraw commands to QuickDraw GX shapes “on the fly” is probably more 
useful. If your needs are different, you can use the GXConvertPICTTbShape routine 
to convert a PicHandle into a gxPicture shape. 

The routines we’ll use are GXInstallQDTransIator and GXRemoveQDTranslator, 
GXInstallQDTranslator tells QuickDraw GX to begin translating QuickDraw 
commands into QuickDraw GX shapes, and GXRemoveQDTranslator tells 
QuickDraw GX that we’ve completed drawing. These routines are used in 
conjunction with a third routine, called a gxSpoolProc, which yon create. Your 
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gxSpooIProc routine will have the following format and will be called whenever 
QuickDraw GX completes a new shape during the translation: 

OSErr MyShapeSpoolProc(gxShape currentShape, long refCon); 

The currentShape parameter contains the QuickDraw GX shape that the translator 
just created, and the refCon parameter is a programmer-defined value that you pass 
to GXInstallQBTranslator. \bu needn’t use the refCon parameter {you can pass nil), 
but as we’ll see in a moment, the refCon can be very handy. 

The code in Listing 10 shows the basic QuickDraw GX print loop, with support 
added to translate QuickDraw commands into QuickDraw GX shapes. 


The code in Listing 10 contains nrequire, require, nrequireactian, and 
requireaction macros, which are discussed in the article "Living in an Exceptional 
World" in develop Issue 11. These macros, which don't require QuickDraw GX 
themselves, are now included in the QuickDraw GX interface fife GXExcepHans.h.* 


Listing 10 - MyGXPrintLoop 


OSE r r MyGXP ri nt Loop(MyDoc umentP t r whi c hDoc ume nt ) 


OSErr 

long 

short 

gxViewPort 

Point 

gxFormat 

Kect 

gxSbape 

MySpo olDat aEe c 


err; 

firstPage F lastPage, numPages, pg; 

oldPage; 

printViewPort; 

patStretch = {1,1}; 

pageFonnat; 

everywhereRect ; 

pageShape; 

spoolData; 


oldPage = whichDocuinent->curPage; 

/* Determine which pages the user selected to print, and print 
only those pages that are actually in the document. */ 
GXGetJobPageRange(whichDocument->documentJob, afirstPage, fclastPage); 
if {lastPage > whichDocument->numPages) 
lastPage = whichDocument->numPages; 

/* Calculate the number of pages to print and begin printing. */ 

numPages = lastPage - firstPage + 1; 

err = GXGetJobError(whichDocument->documentJob); 

nrequire(err, PageRangeError); 

GXStartJob[whichDocument->documentJob , whichDocument->documentTitie, 
numPages); 

err = GXGetJobError(whichDocumentdocumentJob); 
nrequire{err, StartJobFailed); 

/* Create a new view port for printing and set our translator 
rects to "wide open" so that they include all data we r re 
drawing. For each page we print, call GXStartPage, draw, 
and call GXFinishPage. */ 

SetRect(keverywhereRect, 0, 0, 32767, 32767); 
printViewPort = GXNewViewPort(gxScreenViewDevices); 

(continued on next poge) 
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Listing 10*. MyGXPrinhoap (continued) 

for (pg = firstPage; (err = noErr) && (pg <= lasiPage); pg++) 

{ 

/* Get the page's format and start printing the page. */ 
pageFormat = whichDociinient->pageFonnat[pg - 1]; 
if (pageFormat == nil) 

pageFormat = GXGetJobFormat(whichDocument->docamentJob, 1); 
GXS t ar t P age (whic hDocumeut->doc time nt Job, pg, pageFormat, 1, 
fcprlutViewPort); 

err = GXGetJobError( whichDociment->docujnentJob); 

/* If there were no errors, set up the translator, draw 
the QuickDraw data for current page, and remove the 
translator. */ 

nrequir e(err, Star tP age F ailed); 
spoolData.printViewPort = printViewPort; 

GXGetFormatDime n sions(page Format, & spoolData.pageAre a, nil); 
GXInsta11QDTr ans1ator(whic hDocume n t->docume ntWindow, 
gxDefau1tOptionsTranslation, &everywhereRect, 
SeverywhereRect, patStretch, HyPrintAShape, &spoolData); 
whichDocument“>curPage = pg; 

SetPort{whichDocument->documentwindow); 

HyDrawContents(whichDocument->documentWindow); 
GXRemoveQDTranslator(whichDocuinent~>documentwindow, nil}; 
GXFinishPage(whichDGCument->documentJob); 

} 

Start?ageFailed: 

GXFiaishJob(whichDocument->documentJob); 

err = GXGetJobError(whichDocument">documentJob); 

GXDisposeViewPort(printViewPort); 

whic hDocument->ciir Page = oldPage; 

StartJobF ailed: 

PageRangeError: 
return err; 


Several important tilings are going on in the cotie in Listing 10. You may recognize 
the basic QuickDraw GX print loop, which consists of everything in MyGXPrintLoop 
except the view port and translator routines. The first thing we do in the print loop is 
create a gx ViewPort object, because GXStartPage needs to know which view ports 
well he drawing to. Only shapes drawn in the specified view r ports will be printed. 

For our purposes, one view port will suffice, so that's all we create. 

There are two basic print loop methods for QuickDraw GX: the first uses GXPrintPage 
to print a single gxPicture shape; the second method uses the GXStartPage and 
GXFinishPage routines. In the second method, the application specifies a list of view 
ports, and any QuickDraw GX drawing that occurs in any of these view r pons is 
instead redirected to a print file. Since our application draws several shapes on a page, 
it makes sense to use the GXStartPage and GXFinishPage approach. If we had only 
one shape to print (for instance, if we had used GXConvertPICTToShape), or if our 
gxSpoolProc collected all the converted shapes into one gxPicture shape, using 
GXPrintPage w r ould make more sense. 
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Notice that the custom page formats that we've added to our application are 
supported, and they require only a couple of lines of code. Recall that in this 
application we’ve decided to use nil to represent the default job format. If the current 
page's format reference ID is not nil, we pass GXStartPage the reference; otherwise, 
we pass the gxjob object's default format. This default format is always positioned as 
the first format in a gxjob, so we can obtain it as follows: 

pageFormat = GXGetJobFormat[whichDocument->documentJob, 1); 

Before we can issue our QuickDraw" drawing commands, we must call 
GXInstallQDTranslator. Because all QuickDraw drawing calls arc ignored by the 
QuickDraw" GX printing routines, we need to translate all QuickDraw' commands 
to QuickDraw" GX shapes for printing- In the GXInstallQDTranslator call, we 
specify that we w T ant to use the default translation options, that w r e don't want to 
stretch patterns, and that our shape-handling routine is called MyPrintAShape. 
Finally, remember the refCon parameter we discussed earlier? Well, here's where it 
comes into play. In the refGon, we pass a pointer to a MySpoolDataRec, which is 
defined as 

typedef struct MySpoolDataRec { 
gxRec tang1e pageArea; 

gxViewPort printViewFort; 

} MySpoolDataRec, *MySpoolDataPtr ; 

The MyPrintAShape routine is passed each QuickDraw GX shape that is created as 
the result of the QuickDraw translation. We can print each shape because a pointer 
to our MySpoolDataRec is passed in the refCon parameter of MyPrintAShape. Wc 
print a shape by attaching the MySpoolDataRec.printViewPon to the current shape, 
and hen drawing the shape. We use the page rectangle in the MySpoolDataRec to 
determine whether a translated shape w ill appear on the printed page. If the shape 
isn't on the page, it doesn't make sense to w aste time and disk space spooling it. 
Listing 11 shows how cleanly this all fits together. 


/* Page rectangle. */ 

/* View port we're printing in. */ 


Listing 11. MyPrmtAShope 

OSErr MyPrintAShape{gxShape currentStape, long refCon} 

{ 

MySpoolDataPtr spoolData; 

gxS hape Type t heS hapeType; 

spoolData = (MySpoolDataPtr) refCon; 
theShapeType = GXGetShapeType(currentshape); 

/* Don’t waste time spooling the shape if it's being drawn off 
the page. */ 

if ((theShapeType == gxEmptyType) |[ (theShapeType == gxFullType) || 
(theShapeType = gxPictureType) | 

GXTouche s Bounds S h ape(£s poo1D at a->pageArea, cur rents hape)) { 
GXSetShapeViewPorts(currentShape, 1, &spoolData->printViewPort); 
GXDrawShape(currentShape); 

} 

return (OSErr) GXGetGraphicsError(nil); 

} 
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Back in our print loop, we simply draw our page’s QuickDraw representation 
between the GXLjstallQDTranslator and GXRemoveQDTranslator calls, 

QuickDraw commands are translated to QuickDraw GX shapes and printed in one 
fell swoop, 

PRINT ONE COPY 

A soon-to-be-familiar sign oi the QuickDraw GX application will be the Print One 
Copy command in the application’s File menu. The option to print one copy of a 
document without any dialogs is a big convenience to the user, and it requires only a 
few T minutes of coding to support. 

In addition to changing the necessary menu setup and handling routines, we need to 
add a routine to support Print One Copy (Listing 12). Tn this routine, we temporarily 
reset three of the printing options that the user may have previously changed. F irst, 
w^e set up the print job so that it prints only one copy. The number of copies last 
printed is stored in the gxjob object, and we w'ant to make sure that if the user 
previously printed multiple copies of a document, only one copy comes out of the 
printer when Print One Copy ls chosen. Second, we indicate that we want to print all 
pages of the document, rather than the last page range used. Finally, die output 
should come out of the primer. If the job was last primed to a file, well need to change 
the job object’s “Print to disk” setring. Once again, we call upon the Collection 
Manager, although this time we access the job collection. 


listing 12 . MyPrlntOneCopy 

OSErr MyPrintGneCopy{MyDocumentP tr whichDocument) 

{ 

OSErr err; 

Collection jobCollection; 

gxCopiesInfo copieslnfo; 

gxFileDestinationlnfo destlnfo; 
gxPageRangeln to pageRangeln fo; 

Ptr oldCopiesInfo = nil, oldPageRangelnfo .« nil, 

oldDestlnfo = nil; 

long oldCopiesSize, oldPageRangelnfoSize, 

oldDestlnfoSize; 

/* Get the job collection and set it up to print one copy. */ 
jobCollection = GXGetJobCollection(whichDocument^documentJob); 

/* Set number of copies to 1. */ 
copiesInfo.copies = 1; 

err = MyReplaceCollectionltemftcopieslnfo, sizeof(gxCopiesInfo), 

gxCopiesTag, gxPrintingTagID, jobCollection, koldCopiesInfo, 

&oldCopiesSize}; 

nrequire(err, ReplaceCopies error); 

/* Set page range to "all", */ 

pa geRan geIn f o.simp!eRan ge.optio nCho sen = gx De fauItP a geRang e; 
pageRangelnfo.minFromPage = 1; 
pageRangelnfo* simpleRangeTromPage = X; 
pageRangelnfo.maxToPage - whichDocument->nuinPages; 
pageRangelnfo.simpleRange.toPage - whichOocuinent->numPages; 
pageRangelnfo.simpleRange.printAll = true; 

(continued on next page) 
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Listing 12. MyPrintOneCopy fconfmuedj 

err = MyReplaeeCollectioiiItem{ & pa geRange Info , 

si z eo£(gxPageRangelnfo), gxPageRangeTag, gxPrintingTagID, 
jobCollection, SoldPageRangelnfo, SoldRageRangelnfoSize); 
nrequire(err, Rep1a ceP ageRa nge_e rror); 

/* Set destination to "printer". */ 

dest!nfo*toFile = false; 

err = MyReplaceCollectionXtem(&destInfo, 

sizeof{gxFileDestinationlnfo), gxFileDestinationTag, 
gxPrintingTagIDv jobCollection, SoldDestlnfo, 
fcoldDestlnfoSize); 

nrequire(err, ReplaceDestinationerror); 

/* Print one copy of our document* */ 
err - MyFrintDocument{whichDocument); 

/* Restore original number of copies, page range, and output 
destination in case anybody uses that info, */ 

ReplaceDestinationjerror: 

HyReplaceCollectionltern(oldDestInfo, oldDestlnfoSize, 

gxFileDestinationTag, gxPrintingTagID, jobCollection, nil, nil); 
ReplacePageRange_error: 

MyRep1ac eC o11ec tionItem(o1dPa geRangeInfo, oidP ageRangeIn f oSiz e, 
gxPageRangeTag, gxPrintingTagID, jobCollection, nil, nil); 

Rep1ac eC opies_e rro r; 

MyReplaceCoIlectionltem(oldCopiesInfo, oldCopiesSize, gxCopiesTag F 
gxPrintingTagID, jobCollection, nil, nil); 

/* Dispose of pointers that MyReplaceCoIlectionltem created. */ 
if (o1dCopie sInf o) 

Dispos ePtr(oldCopiesInfo}; 
if (oldPageRangeInfo) 

DisposePtr(oldPageRangelnfo); 
if (oldDestlnfo) 

DisposePtr(oldDestlnfo); 
return err; 


The MyReplaceCoIlectionltem routine, which I created for the Simple Sample GX 
application, has the format 

OSErr MyReplaceCollectionItem{void *newData, long collectionltemSize, 

OSType collectionType, long collectionID, Collection 
whichCollection, Ptr *oldData, long *oldDataSize); 

This routine replaces a collection item and returns a copy of its old data. It takes a 
pointer to die collection data we want to store, and the size, type, ID, and collection 
to store it in. In the last two parameters, you pass a reference to a pointer in which to 
store the existing data and a reference to a long word in which to store its size. If the 
oldData pointer is nil, the existing data is not returned; otherwise, a new pointer is 
created in the oldData parameter, and the data is returned there. 


MyReplaceCoIlectionltem allows you to replace a collection item, execute some 
code, and then restore the collection item. That’s exactly w r hat we do in the 
MyPrintOneCopy routine. 
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DRAG-AND-DROP PRINTING 

The final thing that a QuickDraw GX-aware application should support is the new 
attribute of the 'pdoc' Apple event, enabling users to print documents by dragging 
their icons to desktop printers. You need to make only a few changes to your current 
pdoc’ Apple event handler, as you can see from Listing 13, With these changes to the 
Apple event handler, our conversion of the QuickDraw sample application to one 
that's QuickDraw GX aware is complete. 

For information on the r pdoc* Apple event, see Inside Macintosh; 

/nterappA'cafron Communication, Chapter 4.* 


Listing 13 * 'pdoc 1 Apple event handler, modified for QuickDraw GX 


pascal OSErr MyHandlePDOCfAppieEvent *theAppleEvent, AppieEvent *reply, 
long myRefCon) 


{ 


OSErr 

AEEtescList 

FSSpec 

long 

AEKeyword 

DescType 

Boolean 

Size 

MyDocumentPtr 


err; 

docList, dtpList; 
myFSS, dtpFSS; 
itemsInList, i; 
theKeyword; 
typeCode; 

draggedToDTP = false? 

actualSize? 

newDocument; 


/* See if the document was dragged to a desktop printer- *f 
err = AEGetAttributeDesc(theAppleEvent, keyGptionalKeywordAttr, 
typeAEList, SdtpList); 
if (err — noErr} draggedToDTP = true; 

/* If we dragged to a desktop printer, get the name of that 
printer and then throw away the description list for it. */ 
if (draggedToDTP} { 

err ~ AEGetNthFtr(sdtpList, l f typeFSS, ttheKeyword, &typeCode, 
(Ftr) frdtpFSS, sizeof(FSSpec), fcactualSize); 

AEDisposeDesc(&dtpList); 

> 

/* Get our document list. */ 

err = AEGetParamDesc(theAppIeEvent r keyDirectObject, typeAEList, 
idocList ); 

nrequire(err, AEError); 

/* Make sure we've accounted for all of the parameters passed, 
and count the number of documents passed in. */ 
err = MyCheckAEParams(theAppieEvent); 
nrequire(err, AEError); 

err = A£CountIterns(fidocList, fritemsInList ); 
nrequire(err, AEError); 

/* For each entry in the doc list, load it, print it, and close it. */ 
for (i = 1; i <= itemsInList? i++) { 

err = AEGetNthPtr(&docList, i, typeFSS, StheKeyword, &typeCode, 

(Ptr) fcmyFSS, sizeof(FSSpec), £actualSize); 
nrequire(err, AEEntryEr ror); 


(continued on next page} 
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Listing 13. 'pdoc' Apple event handler, modified for QuickDraw GX (continued) 

/* Load the document, */ 

err - MyCreateDocument(kDefaultTitle, finewDocumentJ ; 
nrequire(err, CreateDocFailed); 
err = MyFSLoadDocument(nevDocument f kmyFSS); 
nrequire(err, LoadDocFailed); 

/* If we dragged to a desktop printer, select that as the 
output printer for this job, and print one copy- */ 
if { draggedToDTP) { 

GXSelec tJobQut put Print er(newDocument->docuinent Job, dtpFSS-name); 
err = MyPrintOneCopy(newDocument); 

} 

else /* "Print" chosen from Finder, Show dialog and print. */ 
err - MyPrintDocument(newDocument); 

/* Close the document once it's printed, +/ 

LoadDocFailed: 

HyDisposeDocument(newDocument); 

> 

/* When we're all done, throw away the document list and exit, */ 
CreateDocFailed: 

AEEntryError: 

AEDisposeDesc(sdocList); 

AEError: 

if (gQuitAfterPrinting) 
gQuitting = true; 
return err; 

1 


WHERE TO TAKE IT FROM HERE 

Now that you know how to add QuickDraw' GX printing to a QuickDraw 
application, go do it! Think of all the features you’ll instantly support by being 
QuickDraw' GX aw r are. The time hit to gain this level of compatibility is minimal for 
most applications, and well worth it 

Still not convinced? Take the sample applications and print with both versions under 
QuickDraw GX. Even this simple program show's that if your applications aren’t 
QuickDraw GX aware, you (and your users) are really missing out. 


RELATED READING 

* inside Macintosh: QuickDraw GX Printing and Inside Macintosh: QuickDraw GX 
Environment and Utilities [Addison-Wesley, 1994). 

* "Getting Started With QuickDraw GX" by Pete ("Luke") Alexander, develop 
Issue 15. 

* "Developing QuickDraw GX Printing Extensions" by Sam Weiss, develop Issue 15. 


Thanks to our technical reviewers Pete ("Luke'’) 
Alexander, Hugo Ayala, Tom Dowdy, and Ken 
Hittleman. * 
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Making the Most of QuickDraw GX Bitmaps 


Besides letting you do a lot of cool things with geometric shapes and 
typography, QuickDraw GX has useful tools for manipulating bitmaps. 
For example, bitmap shapes (the QuickDraw GX counterpan to 
pixMaps) can be skewed, rotated, and scaled, and transforms allow 
these operations to be performed repeatedly without data loss. Bitmap 
shapes can share image data, can be used to clip other shapes, and can 
reside on disk instead of in memory. This article tells how you can use 
QuickDraw GX to improve the way you handle bitmapped graphics. 



DAVID SUROVELL 


New users of QuickDraw GX w ill probably start by going through Inside Macintosh: 
QuickDraw GX Objects or the article “Getting Started With QuickDraw GX” in 
develop Issue 15* If you 7 re mainly a QuickDraw programmer, however, you may have 
a lot of questions about how QuickDraw GX applies specifically to bitmaps ■— 
probably the most commonly used graphic objects. As it turns out, it can do most 
anything QuickDraw can do, and quite a few useful and exotic new r things besides* 

If you have at least a nodding familiarity with QuickDraw GX, this article will give 
useful tips on how to apply your knowledge to bitmap shapes. If you’re a QuickDraw' 
GX neophyte, this article will confuse you from time to time, but you may learn 
enough to decide to make the leap to QuickDraw' GX. 

CREATING BITMAP SHAPES 


It takes about the same information to create a bitmap shape in QuickDraw' GX as 
it does to make a pixMap in QuickDraw. The biggest difference is that while 
QuickDraw insists that you calculate the size of the image buffer and allocate it 
explicitly, QuickDraw 4 GX can optionally allocate it for you when the shape is created. 
This is illustrated in the code in Listing l, which creates an indexed bitmap shape. 


For indexed pixelSize values (l, 2, 4, or 8), you set the gxBitinap’s space field to 
gxIndexedSpace and its set field to a color set (the QuickDraw 4 GX equivalent of a 
QuickDraw color table) with an appropriate number of entries* Direct pixelSize 
values (16 or 32) require that the set field be nil. For example, to make the routine in 
Listing 1 create a 16-hit bitmap shape, you would set die gxBitmap’s space field to 
gxRGBlfiSpace and its set field to nil. 


DAVID SUROVELL Where there was once one, 
there now are three: after approximately 1500 
years of bachelorhood, David recently married 
(Jane) and achieved fatherhood (Elliot Jvan). He 
once wrote a book on QuickDraw, but that was 
iong ago. When he's not sleeping under his 


desk at Apple, David's passionate avocations 
include auditioning as a guitarist for bands that 
fail to play in public, committing brutal Fouls in 
otherwise friendly soccer matches and basketball 
games, and playing paintball with other rush-hour 
commuters.* 
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Listing 1, Creating an indexed bitmap shape 

gxShape CreatelndexedBitmapShape(long horiz, long vert, 

long targetDepth) 

{ 

gxBitmap bitshapelnfo; 

gxColorSet targetSet; 
gxShape resultShape; 

if {(horiz <= 0) j| {vert <= 0}) 
return nil; 
if (targetDepth > 8) 
return nil; 

// Create a familiar "color" gxColorSet. 

// (The default gxColorSet is a gray ramp.) 
targetSet - GetStandardColorSet(targetDepth); 
if (targetSet == nil) 
return nil; 

// Let QDGX calculate the image buffer block size and allocate it. 

bitshapelnfo. image = nil; 

bitshapelnfo.rowBytes - 0; 

bitshapelnfo,width = horiz; 

bitshapelnfo,height = vert; 

bitshapelnfo.pixelSize = targetDepth; 

bitshapelnfo.space = gxIndexedSpace; 

bitshapelnfo.set = targetSet; 

// Use the default color profile, 
bitshapelnfo.profile = nil; 

resultShape = GXNewBitmap(SbitShapelnfo, nil); 
return resultShape; 

} 


Note that the gxBitmap 3 s rowBytes is a long, not a short as in QuickDraw. This 
means no more convoluted rowByte hacks, no more magic bits needed for flags, and 
no more unreasonable limits on image width. 

Note also that the gxBitmap contains a profile field, a reference to a gxColorProfile 
(essentially an object with ColorSvnc data wrapped inside). If this field is nil, 
QuickDraw GX uses its default profile. Color matching occurs only when the target 
view port has the gxEnab 1 eMatchPort attribute set — by default, it s s off. 

MANIPULATING BITMAP SHAPES 

Once a bitmap shape is created, you can access and change its characteristics with 
GXGetBitmap and GXSetBitmap. 

GXGetBitmap(targetShape, sbitmaplnfo, ^origin); 

// Alter the necessary gxBitmap fields here. 

GXSetBitmap(targetShape, &bitmaplnfo, Sorigin); 
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GXSetBitmap is similar to QuickDraw’s UpdateGWorld; it lets you change bitmap 
depth, color specification, and size. To change specific attributes, you may need to 
modify a combination of fields. 

To change a bitmap’s width or height, set the width or height field If QuickDraw GX 
originally allocated the image buffer, you can set row Bytes to 0 and the image field to 
nil, and QuickDraw GX wil I reallocate the buffer. If you allocated the buffer yourself, 
you’ll have to maintain it yourself 

An image isn't scaled when you change size this way. If you increase the width or 
height, the new areas contain undefined values; if you decrease them, the image is 
truncated. Bitmap scaling is discussed later in this article. * 

To change a bitmap’s pixel depth, set the pixelSize field to the desired depth. If the 
bitmap needs a new color set (which it will, unless the new depth is greater than 8 
bits), create it and assign it to the set field. An example that changes the depth to 
4-bit is shown in Listing 2. 

To change a bitmap’s color characteristics, just change the set, space, and profile 
fields. No changes to pixel data will occur — all pixel values will he interpreted in die 
new color set. To transform pixel values, you’d need to set up a new bitmap shape and 
draw the existing bitmap into it. (The offscreen library' rourine CopyToBitmaps is 
ideal for this.) 


PIXEL VALUE REPRESENTATION 

A raster image is, naturally enough, an array of pixel 
values. For indexed color, each pixel value is an index 
into an associated color set. 

For direct color (16 or 32 bits per pixel), a pixel value is 
converted directly into a color value by expanding bit 
fields of the 1 6- or 32-bit value Into three or Four 16-bit 
unsigned integer values. 

The expansion of direct pixel values depends on the color 
space of the raster image and the "packing" of the color 
components. QuickDraw supports only RGB and a 


handful of packing schemes, but QuickDraw GX supports 
a whole family of color spaces and packing formats, 
some of which are shown in Figure 1. 

The packing types are defined in the gxColorSpaces 
enum in the header file graphics types.h. You'll also find 
definitions for extended color space specifications, such 
as gxRGB165pace (gxRGBSpace + gxWord5CoforPacking} 
and gxARGB325pace [gxLongBColorPacking + 
gxRGBASpace + gxAlphaFirstPackmgf Only explicitly 
defined permutations are valid — you can't just moke up 
your own. 


1-, 24-, or 8-bit 
16-bit 

32-bit 

32-bit 

32-bir 


Index value 


Red 


Green 


Blue | gxRGB 16Space 


MSB 


■ LSB 


X 

Red | Green Blue 


Alpha 

Red 

Green 

Blue 


X 

Flue 

Saturation 

Value 


(Long 10 packing) 


Figure 1. Some QuickDraw GX pixel packing formats 
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Listing 2. Changing the depth of a bitmap shape 

void ChangeDepthToFour(gxShape bitmapShape) 

{ 

gxBitmap imagelnfo; 

if (fbitmapShape 1= nil) && 

(GXGetShapeType(bitmapShape) == gxBitmapType)) 

{ 

GXGetBitmap(bitmapShape, iimagelafo, nil); 
if (imagelnfo*pixelSize != 4) 

{ 

imageInfo*pixelSize = 4; 
imagelnfo.space = gxIndexedSpace; 
imagelnfo.set = GetStandardColorSet(4); 
GXSetBitmapfbitmapShape, &imagetnfo, nil); 

} 

> 

} 


USING DISK-BASED PIXEL IMAGES 

QuickDraw GX provides support For disk-based bitmap shapes. They’re structurally 
the same as regular bitmaps, except that their image data is contained in a file, so 
they’re always drawn from disk. Ten calls to GXDraw$hape{diskBitmap) means 
QuickDraw GX reads the entire file from disk ten times, (QuickDraw GX can’t 
assume that you didn’t write into the file between accesses.) The idea is that the file 
system’s disk caches will do the work; it the file wasn’t changed, subsequent reads 
should be cached. 


Make sure the file size is al least as large as the bitmap, or you'll get an 
"unexpected end of file" error. * 

Disk-based bitmaps have limitations. For one thing, certain routines can’t be 
performed on them —GXSetShapePixel, for example. (See Inside Macintosh: 
QuickDraw GX Graphics for the complete list.) You can’t use disk-based bitmap shapes 
as drawing destinations. II you draw into the data you trigger an error* 

So how do you create a disk-based bitmap? As shown in Listing 3, you first set the 
gxBitmap’s image field to gxBitmapFileAliasImageValue* After creating the bitmap 
shape, create a tag of type gxBitmapFileAliasTagType containing an alias record that 
references the file containing the target raster data and attach it to the shape* 

ACCESSING IMAGE DATA 

You can manipulate the image data of bitmap shapes directly. If the image data is 
maintained by your application, all you have to do is call GXChangedShape 
afterward* If the image data was allocated by QuickDraw GX, it’s more complicated; 

1. Force the shape to be heap-resident with GXSetSh ape Attributes. 

2. Lock the shape with GXLockShape and check for an error* 

3. Call GXGetShapeStructure to obtain a reference to the image 
data* 

4. Read from or write to the image data as desired* 
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Listing 3+ Creating a disk-based bitmap 

gxShape CreateDiskBitmapfFSSpec *fsData, gxBitmap *targetBM) 

{ 

gxBitmap localBM; 

g x S h ape t ar ge t. S hap e; 

g xTa g tar getTag; 

if {(fsData == nil) || (targetBM == nil)) 
return nil; 
targetShape = nil; 

targetTag - CreateBitmapAliasTag(fsData r OL); 
if (targetTag !^ nil) 

{ 

localBM =*= +targetBM; 

localBM,image - gxBitmapFileAliasImageValue; 
targetShape = GXNewBitmapf&localBM, nil); 
if (targetShape I- nil) 

GXSetShapeTags(targetShape, gxBitmapFiXeAliasTagType, 
lL r -1L, 1L, stargetTag); 
GXDispcseTag{targetTag); 

} 

return targetShape; 


gxTag CreateBitmapAliasTagfFSSpec *bitmapFS, unsigned long fileOffset) 

{ 

struct gxBitmapDataSourceAlias *aliasRecordPtr; 
gxTag targetTag; 

FSSpec targetFS; 

AliasHandle aliasHdi; 

GSErr iErr; 

long aliasSize, aliasRecordSize; 

Boolean wasChanged; 


targetTag ® nil; 
aliasHdi = nil; 
aliasRecordPtr = nil; 


// Create an alias and resolve it, 

iErr - NewAlias(nil, bitmapFS, saliasHdi); 

if (iErr == noErr) 

iErr = ResolveAlias(nil, aliasHdi r &targetFS, swasChanged); 


// Build up a compact representation for inclusion into a gxTag, 
if (iErr == noErr) 

{ 

aliasSize = GetHandleSize((Handle)aliasHdi); 
aliasRecordSize = aliasSize + 2 * sizeof(long); 
aliasRecordPtr = (struct gxBitmapDataSourceAlias*) 

NewPtr(aliasRecordSize); 
iErr = MemErrorf); 

> 

(continued on next page) 
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Listing 3* Creating a disk-based bitmap (continued) 

// Create the gxTag. 
if (iErr = noErr) 

{ 

// Create a gxBitmapDataSourceAlias with specified fileOffset 
// and appropriate aliasRecordSixe and aliasRecord, 
aliasRecordPtr->fileOffset = fileOffset? 
aliasRecordPtr->aliasRecordSize = aliasSize; 

BlockMove(*aliasKdl , saliasRecordPtr->aliasRecordf0 ] f aliasSize)? 
targetTag = GXNewTag(gxBitmapFileAliasTagType, aliasRecordSiz e f 

aliasRecordPtr }; 

} 

// Clean up. 
if {aliasHdl 1= nil) 

DisposeHandle((Handle)aliasHdl); 
if {aliasRecordPtr 1= nil) 

DisposePtr((Ptr)aliasRecordPtr ); 

return targetTag; 

> 


5, I f t h e i m age d a ta w as ch a nge d, ca 11 GXCh an ge d S hape, 

6, Unlock the shape with GXUnlockShnpc. 

7, Gill GXSetShape Attributes to allow the shape to be cached again, 

GXLockShape loads an image into memory, so it might not succeed if there isn’t 
enough memory. And don’t forget to check a bitmap shape’s space field before 
processing die shape -— don’t assume that bitmap images are alw ays in RGB space. 

See Listing 4 for an example of changing a bitmap shape’s data directly. 

MEMORY ISSUES 

Raster surfers and Photoshop junkies know that raster images can be memory hogs; 
it’s easy to run our of application heap w hen you allocate them. So what happens 
when QuickDraw GX runs out of memory? It doesn’t. Well, almost never, l lere are 
the steps it will go through, in order, to deliver die memory you need; 

1. Flush out-of-date caches. 

2. Flush up-to-date caches. 

3. If allowed, grow the current gxHeap. 

4. Unload shapes and other objects to disk. 

5. Give up, and return an error. 

Most QuickDraw developers resort to some sort of GrowZoneProc to handle a 
tight application heap. QuickDraw GX provides a tiered response to abnormal 
occurrences. Items 1 through 4 above return notices (in the debugging version of 
QuickDraw GX); item 5 returns an error. All you have to do is implement a routine 
to handle die notices and errors. 
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Listing 4. Directly changing an indexed bitmap shape 

void InvertBitmap£hape(gx£hape sourceBits) 

{ 

gxBitmap sourcelnfo, *sourceInfoRe£; 

gxShapeAttribute curAttributes; 
unsigned char *sourcePtr, *rowPtr; 

long sourceRowSize, structLen, i, j; 

Boolean isQDGXImage; 

// Make sure that this is an indexed bitmap shape, 
if (sourceBits == nil) 
return; 

if (GXGetShapeType(sourceBits) != gxBitmapType) 
return; 

GXGetBitmap{sourceBits, ksourcelnfo, nil); 
if (sourcelnfo.pixelSize > 3) 
return; 

if (sourcelnfo.image == gxBitmapFileAliasImageValue) 
return; 

// If the image data was allocated by QuickDraw GX... 
isQDGXImage = (sourcelnfo,image == nil); 
if (isQDGXImage) 

{ 

// Load and lock the image data. 

curAttributes = GXGetShapeAttributes(sourceBits); 

if ( l [curAttributes £ gxDirectShape)) 

GXSetShapeAttributes(sourceBits, 

curAttributes | gxDirectShape); 

GXLockShape(sourceBits); 
if {GXGraphicsError{nil) 1=0) 
return; 

// Get a reference to the image data. 
sourcelnfoRef = 

(gxBitmap*)GXGetShapeStructure{sourceBits r sstructLen); 
if ((sourcelnfoRef — nil) || (structLen < sizeof(gxBitmap))) 
return; 

sourcelnfo = *sourcelnfoRef; 

} 

// Invert index values, one row at a time. 
sourcePtr = (unsigned char*)(sourcelnfo.image); 
for (i = sourcelnfo.height; i > 0; i—) 

{ 

rowPtr = sourcePtr; 

sourceRowSize = sourceInfo.rowBytes; 

while (sourceRowSize-— > 0) 

{ 

*rowPtr = ^*rowPtr; 
rowFtr++; 

> 

(continued on next page) 
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Listing 4- DirecHy changing an indexed bitmap shape (continued) 

// Skip to the next row. 

sourcePtr = (unsigned char*jsourcePtr + sourcelnfo.rowBytes; 

} 

GXChangedShape(sourceBits); 
if (isQDGXImage) 

{ 

GXUnlockShape(sourceBits); 

GXSet5hapeAttributes(sourceBits, curAttributes ); 

} 

} 


GEOMETRIC OPERATIONS 

One of the niftiest features of QuickDraw GX is the ability to perform geometric 
operations on bitmap shapes. Most of the operators that apply to geometric shapes 
also apply to bitmaps: rotate, scale, skew, perspective, and clip. In comparison, 
QuickDraw provides only three geometric operators: scale, clip, and mask. 


ALTERING THE TRANSFORM VERSUS THE GEOMETRY 

When you change a bitmap shape’s geometry (that is, its actual pixel data), whether 
by rotating, skewing, applying perspective, or scaling, you normally lose image data 
— it’s often impossible to return the image to its pristine state. 

You can eliminate this data loss by instead applying geometric operators to a shape's 
transform . A shape can make use of a 3 x 3 matrix to mathematically change its 
appearance when rendered without changing the underlying data. This is especially 
important for bitmaps. Figure 2 shows both possibilities of multiple rotations of a 
bitmap. 






Geometry rotation 


ill III 






Transform rotation 


Figure 2. Successive rotations of a bitmap 


Rotation, translation {change in origin), skew, perspective, and scale operations can 
all be performed on transforms direedy, by GXRotateTransform, GXSkew r Transform, 
and so forth, or indirectly, using the gxMapTransforniShape attribute. 

When a shape’s gxMapTrans form Shape attribute is set, geometric operations 
automatically apply to its transform rather than its geometry. Bitmap and picture 
shapes default to having this attribute set; other shapes begin with it off. This 
means that if you convert a polygon shape {for example) to a bitmap shape, the 
gxMapTransformShape attribute won’t automatically be set 

When a QuickDraw GX routine modifies a bitmap shape’s geometry, a clip shape is 
often attached to define the geometric extent of the modified bitmap. More often 
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than not, the bitmap’s image buffer is expanded, as shown in Figure 3. Rotating a 
bitmap’s geometry can increase its memory requirements by over 40%. 


Original 

bounds 



Original bitmap 


Rotate 45 CT 


New bitmap 



New bounds 


Clip shape 


Figure 3* Effect of GXRotateShape on bitmap geometry 

ROTATION 

There aren’t many QuickDraw programmers who haven’t wished for a simple way to 
rotate bitmaps. GXRotateShape takes parameters for the target shape, degrees 
clockwise to rotate, and center point of rotation, as shown in Listing 5. 


Listing 5* Rotating a bitmap shape 

void KotateBitinapigxShape targetShape, Fixed theta) 

( 

gxBitmap targetBM; 

gxFoint origin, shCenter; 

// Determine the bitmap shape's current center point* 
GXGetBitmap(targetShape, StargetBM, Sorigin); 
shCenter.x = ff(targetBM,width) / 2 + origin.x? 
shCenter.y = ff(targetBM.height) / 2 + origin.y; 

// Rotate it around its center point. 

GXRotateShape(targetShape, theta, shCenter.x, shCenter.y); 


SKEWING AND PERSPECTIVE 

Skewing and perspective are just as much fun as rotation, and even more useful as 
general-purpose graphic effects. The code in Listing 6 illustrates a simple type of 
perspective; Figure 4 shows the results of this perspective mapping. 

SCALING 

You can expand or shrink bitmap shapes, like other shape types, with GXScaleShape. 
QuickDraw pixMaps are scaled by setting the destination rectangle passed to 
Copy Bits, whereas GXScaleShape uses a scaling factor. To convert your QuickDraw 
bitmap sealing code into the equivalent QuickDraw GX code, you have to calculate 
tliis scaling factor. Listing 7 show r s how 7 . 

You can flip a bitmap horizontally or vertically by using negative scaling values. * 
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Listing 6* Applying perspective to a bitmap shape 


void TrapezoidalWarpfvoid] 


{ 

gxShape bitsShape, warpShape; 
long trapezoidData[] - 


1L, 4L, 

f f (130 ), ff(100), f f (170) j. ££(100), 


ff (200) , ff [200) r ff£100}, ££(200) 
K 


bitsShape = CreateBasicBitmap$hape (); 

warpShape = GXWewShapeVector(gxPolygonType, trapezoidData); 
if (warpShape 1= nil) 

{ 

ShapeSetPolyMap(bitsShape, warpShape}; 

GXDisposeShape(warpShape); 

> 

GXDrawShape(bitsShape}; 


} 


void ShapeSetPolyMap(gxShape targetShape, gxShape mappingShape] 

{ 

gxKectangle boundsRect; 


gxPolygon 

gxMapping 

gxShape 

long 


*mapPoly, *targetPoly; 
theMapping; 
targetBounds; 
ignored; 


if (targetShape “ nil) 
return; 

if ((mappingShape == nil) 

|| (GXGetShapeType(mappingShape) 1- gxPolygonType)) 
return; 

// Determine the dimensions of the target shape, 

GXGetShapeBounds(targetShape, 0L, fcboundsRect}; 
targetBounds = GXNewRectangle(&bou ndsRect); 
if (targetBounds ==* nil) 
return ; 

// Scale the mapping shape to the dimensions of the target shape. 
GXSetShapeBounds(mappingShape , &boundsRect); 

GXSetShapeType(targetBounds, gxPolygonType); 

// Load £ lock both shapes so that their structures can be accessed. 
GXSetShapeAttributes{mappingShape, 

GXGetShapeAttributes(mappingShape) | gxDirectShape); 
GXLockShape(mappingShape); 

GXSetShapeAttributes{targetBounds , 

GXGetShapeAttributes(targetBounds) | gxDirectShape); 
GXLockShape[targetBounds}; 


(con/meed on nexf pagej 
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Listing 6. Applying perspective to o bitmap shape (continued) 

U NOTE: Structure is actually of type gxPolygon. 

mapPoly = [gxPolygon*)GXGetShapeStructure^mappingshape, ^ignored); 

targetPoly = {gxPolygon*)GXGetShapeStructure(targetBounds, &ignored ); 

if ((mapPoly 1= nil) && (targetPoly I= nil)) 

{ 

// Skip past the gxPolygons contour count to the first contour. 
mapPoly = (gxPolygon*)((Ptr)mapPoly + sizeof(long)); 
targetPoly = (gxPolygon*)((Ptr)targetPoly + sizeof(long ))} 

// Calculate the desired shape mapping. 

// PolyToPolyMap() is in "mapping library.c. 11 
PolyToPolyMap(targetPoly, mapPoly, StheMapping); 

} 

// Release both shapes from bondage, 

GXUnlockShape(mappingShape); 

GXSetShapeAttributes(mappingShape, 

GXGetShapeAttributes(mappingShape) & ^gxDirectShape); 
GXUnlockShape(targetBounds); 

GXSetShapeAttributes(targetBounds , 

GXGetShapeAttributes(targetBounds) & -gxDirectShape)? 

// Set the target shape's mapping as desired, 

GXSetShapeMapping£targetShape, stheMapping); 

GXDisposeShape(targetBounds); 



Before perspective 



After perspective 


Figure 4. Applying perspective to a bitmap shape 

CLIPPING AND MASKING 

QuickDraw GX can do some near tricks with dipping. These tricks work with bitmap 
shapes, too. For example, to create a gradient-filled polygon, you can make a 
rectangular bitmap shape with a gradient arid then set the polygon shape as the 
bitmap's clip shape. (For another example, see Graphical Truffles in this issue.) 
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Listing 7* Calculating a scaling factor 

void BitmapShapeScaleQDStyle(gxShape targetShape, Rect *qdSourceR, 

Rect *qdDestR) 

{ 

gxFoint centerPt; 

fixed scaleFactorH, scaieFactorV; 


scaleFactorH = FixRatic{qdSourceR.right - qdSourceR.left , 
qdDestR.right - qdDestR.left); 
scaieFactorV = FixRatiofqdSourceR.bottom - qdSourceR.top, 
qdDestR.bottom - qdDestR.top); 
cersterPt.x - ff((qdDestR.right + qdDestR.left) / 2); 
centerPt.y = ff((qdDestR.bottom + qdDestR.top) / 2); 

GXScaleShape(targetShape , scaleFactorH, scaieFactorV! centerPt.x, 

centerPt.y); 

GXMoveShapeTo(targetShape, ff(qdDestR.left), ff(qdDestR.top)); 
GXDrawShape(targetShape); 


You can use 1-bit bitmap shapes as clip shapes* too. The effect is just like that of 
Copy Mask; pixels in the source shape are drawn only where the clipping bitmap pixel 
value is nonzero. (On this issue’s CD, you’ll also find example code that does image 
processing similar to CopyDeepMask using the new transfer modes.) 

Clipping occurs in geometry space, before transform mapping, so □ bitmap's 
dip shape should be based on its bounds rectangle, not its rendered location.* 

To convert geometric shapes into masking bitmap shapes, you can call the 
GXSetShapeType routine to convert the shape to a 1-bit mask bitmap. 

With GXCheckBkmapColor, you can generate a masking bitmap from an existing 
bitmap shape. If you pass GXCheckBitmapColor a color set, it puts 0 in the result 
bitmap for source pixel values that are in the color set. If you pass ir a color profile, it 
puts 0 in the result bitmap for source pixel values that are within the color profile's 
gamut. The result bitmap can be useful for color correction. 

QUICKDRAW GX TRICKS FOR QUICKDRAW DOGS 

QuickDraw GX has ways to do almost anything you can do with QuickDraw. All you 
need to know is how their environments and feature sets compare, and you’ll 
understand how to convert from one to the other. 

THE VIEW PORT LIST VERSUS THE GRAPHICS PORT 

Most of the time you won’t have to concern yourself with view ports at rendering 
time, because there's no sense of the “current port 1 ’ as there is in QuickDraw. Here’s 
the recommended method for drawing an existing shape into a new view port: 

1. G>py thc shape ? s transform and install the desired destination view 
port into the copy. 

2. Call GXDrawShape. 

3. Restore the original transform. 

4. Dispose of the copied transform. 
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Examples of preserving view port lists can be found in the library routine 
CopyToBitmaps and in die DrawShapeGffscreen example later in this article 
(Listing 9). 

BITMAPS AND TRAN5FER MODES 

QuickDraw GX has a lot of transfer modes. This is a good thing, really. Not all 
transfer modes are functionally equivalent to those in QuickDraw, but the transferMode 
library is fairly complete* Many of the capabilities of QuickDraw search procedures 
can be implemented using transfer modes. (The first page of Inside Macintosh: 
QuickDraw GX Graphics has color pictures of the new transfer modes in action*) 

The transfer mode is contained in a shape’s ink. Since transfer modes are applied on a 
per-component basis, you can easily get some groovy effects. For example, you can 
add the hue of one image to the brightness of another. Usually, though, you’ll want 
all components to use the same mode. The transferMode library routine 
SetConimonTransfer will do this for you. 

There are some differences between QuickDraw GX transfer modes and those found 
in QuickDraw; 

* Dithering is a view port feature, not a transfer mode. Halftoning is 
also available on a per-gxViewPort basis. These two features are 
mutually exclusive; you can’t dither and halftone at the same time. 

* Transparency is not a single mode, Irs a whole family of modes 
based on alpha component values* 

* All QuickDraw GX transfer modes occur in color space, while 
some QuickDraw transfer modes are bitwise. 

ONSCREEN BITMAPS 

QuickDraw GX maintains a view device list that mirrors the QuickDraw GDevice 
list. (Utility routines are provided for getting one if you have the other.) The 
Window Manager is patched in a couple of places so that a window’s view port 
transforms and image memory are maintained when it enters and leaves GDevice real 
estate* 

Drawing a bitmap onscreen obeys the screen GDevice’s index entry protections — 
QuickDraw GX doesn’t use indexes reserved by the Palette Manager for other 
applications. If you want to draw an image that uses animated palette entries, you’ll 
need to clone references to the destination view Device color set and profile, and then 
insert those references into the bitmap shape before drawing* Example code that does 
this is on this issue’s CD. 

COPYBIT5 IN QUICKDRAW GX 

Let’s see what it takes to make GXDrawShape do what CopyBits does* GopyBitx has 
several explicit parameters; the source, destination, clipping region, and transfer 
mode. In QuickDraw GX, the source is the bitmap shape. The destination is defined 
by the shape’s view port list. The clipping region is any shape that you attach to the 
bitmap shape with GXSetShapeClip. As mentioned before, the transfer mode is 
contained in the shape’s ink. 

So, to do a Copy Bits-style blit in QuickDraw GX: 
l * Set up the shape’s view port list* 

2. Determine the transfer mode (usually just “copy,” hut it’s your 
choice). 
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3. Adjust the shape clip* Don’t change the device clip or view port 
clip* 

4* Adjust the transform if you want to reposition, scale, skew, rotate, 
or apply perspective to the shape. 

5. Call GXDrawShape. 

6. Clean up as needed. 

QuickDraw GX doesn't implement all of the color capabilities of CopyBits. 

There's no colorizing and no color interpolation for indexed values beyond the end of 
a bitmap's color set," 

DRAWING OFFSCREEN WITH QUICKDRAW GX 

Successive QuickDraw implementations have presented newer and better ways to 
draw into a offscreen image buffer. The QuickDraw GX offscreen library contains 
routines to help maintain the data structures necessary to implement the equivalent 
of a GWorld. 

' I Tie example in Listing 8 uses the CreatelndexedBitmapShape routine from Listing 1 
and the library routine Create Offscreen to create a fully functional offscreen bitmap* 


Listing 8. Creating an offscreen bitmap 


OSErr MakelndexedOffscreen(offscreen *targetOffWorld, long horiz, 

long vert, long targetDepth) 


{ 

gxShape bitsShape; 


if (1CheekArguments(...) 1 
return paramErr; 

bitsShape = CreatelndexedBitmapShape(horiz, vert, targetDepth); 
if (bitsShape == nil) 
return paramErr; 

CreateOffscreen(targetOffWorld, bitsShape); 
return noErr; 


You might think drawing into a QuickDraw GX offscreen bitmap would be difficult, 
but it's not* To draw a shape into the offscreen bitmap, set its view port list to the 
offscreen bitmap’s view port and call GXDrawShape (see Listing 9)* 

BITMAP SHAPES VERSUS PIXMAPS 

Sometimes, converting existing QuickDraw code to QuickDraw GX is impractical. If 
your application needs to use the same data in both offscreen pixMaps and bitmap 
shapes, it can, provided that the bitmap shape is packed the same as the pixMap — 
that is, of identical width, height, pixel depth, and color space. 

To use bitmap shape data in a QuickDraw pixMap, build the pixMap with the 
baseAddr die same as the gxBitmap,image. (Make sure that the bitmap shape is 
locked down.) To use pixMap data in QuickDraw GX, create a gxBitmap with the 
image field set to the base address of the source pixMap. 
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Listing 9* Drawing into on offscreen bitmap 

void DrawShapeOffscreen(offscreen *offGXWorld, gxShape targetShape) 

{ 

gxTransform newXform, savedxform; 

if ((offGXWorld == nil) || (targetShape == nil)) 
return ; 

if (offGXWorld->port == nil) 
return; 

savedXform = GXGetShapeTransform(targetShape); 
newXform = GXCopyToTransfornqnil, savedXform); 
GXSetTransfonnViewPorts (newXfom, lL r & (offGXHorld->port)}; 
GXSetShapeTransform(targetShape, newXform); 

G XDr awS hape(targetShape); 

GXSetShapeTransform(targetShape, savedXform); 

GXDisposeTransform(newXform); 


THE QUICKDRAW GX LIBRARIES 

Several libraries are included with the QuickDraw GX Software Developer’s Kit 
They contain, among other things, routines lor offscreen rendering and converting 
image data between QuickDraw and QuickDraw GX. The library code instructs by 
example and is a good starting point for your own library. 

The library code is not completely tested. You should heat it as template 
code, not a final solution.* 


The offscreen library. This library contains support for offscreen bitmaps, copying 
between bitmap shapes, and simple gradient tills. The offscreen image implementation 
is basic but solid (it lacks some of the features found in QuickDraw GWorlds, such as 
automatic longword realignment of images). The utility routine CopyToBitmaps is 
also useful; it shows a good example of saving a view port list. 

The math library* This library contains a number of useful routines for manipulating 
mappings. The routine PolyToPolyMap is used in tire trapezoidal warp example 
(Listing 6), The header file math routine.h contains essential macros tor conversion 
between fixed-point, floating-point, and integral values. 

The ramp library. Get your gradient fills here. Pleasing to the eye, easy on the 
code. A gradient-filled bitmap can be rotated and clipped, and voila! Gradient-filled 
shapes. 

The qd and oval libraries. The qd library has facilities for conversion of bitmap 
and color data between QuickDraw and QuickDraw GX formats. The oval library 
has real ovals, not those phony squished QuickDraw tilings. 

The fransferMode library. This library facilitates access to a shape’s transfer mode 
information and contains routines for emulating most of the QuickDraw transfer 
modes. It also contains a bonus — one of my favorite routines. If you’ve ever wanted 
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to gel the results of a QuickDraw transfer mode on color values without having to 
use Copy Bits, TransmogrifyColor is for you. Check it out. 

The storage library* This library implements spooling routines for use with 
GXFIattenShape and GXUnflattenShape, which you’ll need for reading and writing 
shapes to and from files. These routines detect errors but don't report them, so 
they’re only useful as templates. 

The camera library. Perspective is cool, but hard to use unless your math skills are 
well developed. This library provides nifty 3 -D techniques. 

AND A FEW MORE THINGS * * . 

Here Fll point out some caveats and additional interesting features of QuickDraw 
GX, just so you know what to look for (and look out for). 

EXECUTION OVERHEAD 

I low fast are QuickDraw GX blits? How slow does an offscreen, 256 x 256, 45°- 
rotated, 32-bit, VXY, gradient-filled bitmap draw into a window on a 4-bit monitor? 
How much for all of these shiny pebbles? It depends. Let’s look at the issues involved. 
QuickDraw GX and QuickDraw have much in common here; 

* They’re fastest when there’s no conversion of value or image 
loeation. 

* Common code paths are optimized inside die API; 8-bit to 8-bit, 

1-bit to 1-bit, 24-bit to 8-bit, no clipping, rectangle clipped. 

* Blits involving complex transformations are usually orders of 
magnitude slower. 

Some transformations require more processing. QuickDraw GX does only 
as much work a$ fhe transformation matrix mandates. From fastest to slowest, the 
order is; no transformation (or translation only); scaling; skewing or rotation; 
perspective. * 


' Fh e ba s i c p e r fo rm a nee gu id el i nes are si milar to au tomot i ve fu e I e ffi c i e ney ra ti ngs — 
though we have no hard estimates, mileage is better on a smooth highway (no color 
mapping, skewing, or scaling) than on surface streets. 

A transform mutation can require a 3 x 3 matrix operation for each pixel value when 
rendered. That's a lot of fixed-point multiplications. If execution speed is critical and 
the mutated version will be used a lot, copy the bitmap shape, mutate the geometry, 
and draw like crazy. Otherwise, mutate the transform and draw T as needed. 

SHARED IMAGE BUFFERS 

A bitmap shape’s raster image buffer can be shared by other bitmap shapes. Just make 
the source bitmap shape’s image field the same as that of another bitmap shape. 
GXCopyToShape uses this sharing of image buffers. If you need a copy of a bitmap 
shape (or a picture that contains bitmap shapes) to have its own image buffer, use 
GXCopyDeepToShape. 

USING BITMAPS AS PATTERNS 

Bitmap shapes can he used as patterns. Unlike QuickDraw, QuickDraw GX has no 
limitation on area dimension or size of raster data in a pattern. To do simple tiling, 
you can just set the bitmap pattern on the shape. 
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You can align the pattern to all destination view ports simply by setting the 
gxPortAlignPattera attribute. This forces all shapes drawn with that pattern in a 
given view port to visually line up with each other* Another pattern attribute, 
gsPortMapPattern, keeps a pattern from being affected by a shape's transform; this 
is useful* for example, when you want a shape rotated and its pattern unrotated, 

BITMAP SHAPE EQUIVALENCE 

Yoii can test Qtii ckDraw GX s!iapes for equi va 1 ence by calling GXEqualShape. 
However, this routine doesn’t account for mapping effects. For example, a bionap 
gradient from black to white would he considered not equal to a white-to-hlack 
gradient bitmap whose transform is rotated 180°, even though the two shapes would 
produce identical results when drawn. 

SIMPLIFICATION 

GXSimplifyShape reduces an indexed bitmap to its simplest representation, even 
reducing the pixel depth when possible. For example, if an 8-bit-deep bitmap shape 
contains only IS colors, GXSimplifyShape will convert it to a 4-bit-deep bitmap. If a 
bitmap is all one color, it will he converted into a rectangle shape — it won’t be a 
bitmap shape any more. 

SUBSET EDITING 

QuickDraw GX provides tools for working with area subsets of bitmaps. A piece can 
be copied from a source bitmap via GXGetBitmapParts, edited, and then blasted back 
into the source image with GXSetBitmapParts. 

Individual pixel values can be accessed with the C iXGetShapePixel and 
GXSetShapePixel routines. Unlike in QuickDraw, these routines don't need to 
reference a gxViewDeviee to determine the color. 

SO GET GOING 

As you can see, QuickDraw GX does some really cool things w ith bitmaps. The 
transforms alone make it worthwhile — it's easy to get addicted to rotating and 
skewing your bitmaps without having to do a lot of work. The new transfer modes 
are great. All the rest is a bonus. In the future, when memory is cheap and every 
machine is fast, you41 see more and more Macintosh systems and applications 
become dependent on QuickDraw GX* 


Thanks to our technical reviewers Pete ("Luke") 
Alexander, Josh Harwich, and Chris Yerga.* 
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GRAPHICAL 

TRUFFLES 

A Cool 

QuickDraw GX 
Clipping Effect 


PETE {"LUKE") ALEXANDER 


Wading through the vast sea of documentation you get 
with the QuickDraw GX Software Developer’s Kit, you 
may not realize ail the cool things this new graphics 
model lets you do. In this column, we’ll look at just one 
of those cool things: clipping one shape to the inside of 
another arbitrary shape. As an illustration, well take a 
bitmapped image of a tropical beach (Figure 1) and clip 
it to the word “BAY” (Figure 2). Figure 3 show's the 
result. There’s a sample application and source code on 
this issue’s CD. 

CREATING THE SHAPES 

We’ll be collecting the results of our operations into a 
picture shape. We’ll assume that the QuickDraw GX 
environment has already been set up and that w r c have a 
window ready to draw into. 

For information on setting up the QuickDraw GX environment 
see "'Getting Started With QuickDraw GX" En develop Issue 15. 

The full details are in /nsrde Macintosh: QuickDraw GX Objects 
and /ns/de Macintosh: QuickDraw GX Graphics* 

We start by creating an empty picture to which we can 

add shapes: 

gxShape thePxcture? 

thePicture = GXNewShape( gxPictureType) *, 

The bitmap shape well he clipping (Figure 1) is stored 
in our application’s resource fork as a ‘pxmp 1 resource. 
We retrieve ir with the GetPixMapShape call from die 
qd library. 



Figure 1* The shape to be dipped 




Figure 2< The clip shape 



Figure 3. Result of dipping Figure 1 to Figure 2 


gxS hape t h eBitmap; 

theBitmap = GetPixMapShape(kPixMapID); 


To create the clip shape, w r e start with a text shape 
containing the word BAY 


PETE ("LUKE") ALEXANDER Regular readers of Luke's columns 
will know that he took his sabbatical from Apple this summer. He 
sent us a postcard; "Hey d udes I While youTe looking out your 
windows at Silicon Valley smog. I'm looking out my windows at the 
rocky faces of Montana. Have you heard of National Parks? 
They're places of unusual beauty set apart from development. 

Not that kind of development! The kind that causes smog. At 


Yellowstone Park I enjoyed the clear air, I found where the buffalo 
roam, and I learned why they call l\ Old Faithful. I'm now flying 
somewhere over Montana (don't worry, I'm steering with my knee), 
admiring the mountains with their lingering snow and enjoying the 
wide open spaces. Oops, mountain ahead and no more room on 
the card/' He signed it, "See you later, Luke" but then crossed out 
the "See you later/' We're worried, really worried.* 


GRAPHICAL TRUFFLES: A COOL QUICKDRAW GX CUPPING EFFECT 65 



































gxShape theClip; 

theClip - GXNewText{3, (unsigned char*) "BAY 11 , nil); 

POSITIONING AND SCALING THE TEXT SHAPE 

Before we set our text shape to he the dip of our 
bitmap shape, we need to move it to the top left corner 
of the bitmap shape and then scale it to encompass the 
entire bitmap. 

We’ll look at two ways to do this. The first method 
takes us through all the steps in the process, while the 
second is simpler and lets QuickDraw GX do more of 
the work for us. 

The origin of a text shape is on the baseline, hut in this 
case, because there are no descenders in the text, we 
just use the bottom left corner of the shape’s bounds. 
We need to offset the text shape by its own height Tom 
the top of the bitmap shape. So we need to know the 
bounds of both the bitmap shape (to find die 
coordinates of its top left corner) and the text shape (to 
calculate its height); 

gxReetangle bitmapBounds, textBounds; 
GXGetShapeBounds(theBitmap, G f ^bitmapBounds); 
GXGetShapeBounds{theClip t 0 , ^textBounds); 
textHeight = textBounds.bottom - textBounds♦top; 
GXMoveShapeToftheClip, bitmapBounds.left, 
bitmapBounds.top + textHeight); 

Our original text shape, which is the default text size oi 
12 points, isn't big enough to cover the entire bitmap 
shape. If we were to do the clipping at this point, we 
would get just a tiny piece of the corner instead of the 
whole bitmap. To get the whole thing, we have to scale 
the text shape to match the size of the bitmap shape. 

F or th e text s h a p e to s ea i e line a r I y, w i th o u 11 a ki ng th e 
font’s hin ting i n to account, we have to tu rn o ff 
QuickDraw GX’s built-in metrics and contour grid- 
fitting capabilities. We do this by setting the shape’s 
text attributes as follows: 

GXSetShapeTextAttributes(theClip, 

gxNoMetricsGridText | gxNoContourGridText); 

Although QuickDraw GX lets us clip to any arbitrary 
shape, clipping is actually limited to primitive shapes 
only. That is, the clip shape must be a shape whose 
geometry and fill properties by themselves define the 
shape; primitive shapes don’t use information from a 
style or transform object. This is not a problem, 
though, because we can easily convert a shape to its 
primitive form. The following call does the job: 

GXPrimitiveShape(theClip); 


The result is a filled path shape (which is a primitive 
shape) representing the outlines of the letters in the 
word BAY, 

Next we need to determine how much to scale the text 
shape to encompass the entire bitmap shape. We do 
this by finding the width and height of both shapes’ 
bounds rectangles and scaling the text shape in each 
direction by the ratio between the two: 

Fixed bitmapftidth, bitmapHeight; 

Fixed textwidth, textHeight; 

Fixed xScale, yScale; 

U Determine the width ratio. 
bitmapWidth = bitmapBounds.right - 
bitmapBounds.left; 

textwidth = textBounds,right - textBounds.left; 
xScale = FixedDividefbitmapWidth, textWidth); 

// Determine the height ratio. 
bitmapHeight = bitmapBounds.bottom - 
bitmapBounds.top; 

textHeight “ textBounds,bottom - textBounds.top; 
yScale = FixedDivide{bitmapHeight, textHeight); 

GXScale5hape{theClip, xScale, yScale, 

bitmapBounds.left, bitmapBounds,top); 

We Ye now scaled the text shape to encompass the 
entire area of our bitmap shape, and we’re ready to 
use it to clip the bitmap shape. But it turns out that 
there’s a shorter way to do this; we can actually 
accomplish the same thing with only three lines of 
code: 

GXSetShapeTextAttributes{theClip, 

gxNoMetricsGridText | gxNoContourGridText); 
GXGetShapeBounds{theBitmap, 0 f ^textBounds); 
GXSetShapeBounds(theClip, ^textBounds); 

As in the earlier method, we turn hinting off and get 
the bounds of our bitmap shape. 'The magic here is 
in the GXSetShapeBounds call: when applied to 
typographic shapes, this call positions and scales the 
text to the new bounds and converts it to a primitive 
shape. That’s it! QuickDraw GX does the hard work 
for us automatically, and we’re ready to set the clip of 
our bitmap shape, 

SETTING THE CLIP SHAPE 

Now that the text shape is positioned and scaled the 
way we want it, w-e’re ready to set it up as the dip of 
our bitmap shape: 

GXSetShapeClip(theBitmap, theClip); 
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This call changes the clip shape contained within the 
transform used by our bitmap shape, replacing it with 
the new clip shape that we’ve created. 

if the same transform were being shared by other shapes, 
QuickDraw GX would make a copy of the transform to associate 
with our bitmap shape, ensuring that the new clip would not affect 
any of the other shapes sharing the same transform,* 

The next step is to add the clipped bitmap shape to our 
picture with GXSetPi clu re Pa res* (Note that we could 
also use the library call Add ToSha pe or the core call 
GXSetShapeParrs to do the same tiling, but I chose to 
be more explicit here.) 

GXSetPictureParts(thePicture, 0 r 0, l f StheBitmap, 
nil, nil, nil); 

The picture now contains a new reference to the 
original bitmap shape, complete with the new dip 
we've added to it* Once there's a reference to it in the 
picture, we don’t need the original reference anymore, 
so we dispose of it: 

GXDisposeShape{theBitmap); 

DRAWING THE OUTLINE 

The last order of business is to draw an outline around 
the dipped bitmap. We can accomplish this by setting 
up the drawing characteristics of our scaled text shape 
to draw the outline and then adding it to our picture* 
To frame the shape with a closed outline, we set its fill 
characteristic to gxClosedFrameFilL Since we want the 
frame to lie outside the geometry of the shape, we set 
its style attributes to gxOutsideFrameStyle* Finally, we 
set the pen size to 3 to get a satisiyingly fat outline, and 
we set the color of the outline to blue: 

GXSetShapeFill(theClip, gxClosedFrameFill ); 
GXSetShapeStyleAttributes[theClip, 

gxOatsideFrameStyle); 
GXSetShapePen(theClip, f£{3)); 

SetShapeCommonColor(theClip, blue); 

Now we can add the outlined shape to our picture and 
dispose of it, as before: 

GXSetPictureParts(thePicture, 0, 0, 1, stheClip, 
ail, nil, ail); 

GXDisposeShape(theClip); 

DRAWING THE PICTURE 

Before drawing our picture, well move it down a little 
from the top left corner of the window. We could do 
this by retrieving the picture’s transform anti shifting it 


down and to the right with GXMoveTransform; 
however, since the gxMapTransformShape attribute 
is set for pictures by default, we can just call 
GXMoveShape: 

GXMoveShape(thePicture, f(2D), ff(15)); 

Finally, we’re ready to draw the picture: 

GXDrawShapefthePicture); 

We're done! The result should look like Figure 3. 

THAT'S ALL, FOLKS 

You’ve had a quick look at one of the many cool things 
you can do with the QuickDraw GX graphics system* 
As you can see from this example, the power and 
flexibili ty of QuickDraw GX can give your application 
the ability to do things you could only dream about 
until now* 


Thanks to Hugo Ayala and Cary Clark for reviewing this 
column,* 


How’re we doing? 

If you have questions, suggestions, or even gripes 
about develop , please don ’t keep them to yourself. 
Let us know what you think. 

Send editorial suggestions or comments to 
AppleLink DEVELOP or to: 

Caroline Rose 
Apple Computer, Inc. 

One Infinite Loop, M/S 303-4DP 
C uperri no, CA 95014 
AppleLink: CROSE 
Internet: crnse@applelnik.apple.com 
Fax: (408)974-6395 

Send technical questions about develop to: 

Dave Johnson 
Apple Computer, Inc* 

One Infinite Loop, M/S 303-4DP 
Cupertino, CA 95014 
AppleLink: JOHNS ON* DK 
Internet: dkj@apple.com 
CompuServe: 75300,715 
Fax: (408)974-6395 
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Pick Your Picker With Color Picker 2.0 


The limitations of the old Color Picker Package forced many developers 
to write their own color pickers. The flexibility of Color Picker version 
2.0 overcomes the old limitations and provides many new features —- 
most notably, use with Color Sync color. Now its easy to design color 
pickers to suit your needs. This ankle describes how to use the new 
Color Picker Manager and take advantage of its customization features 
from within your application. 



SHANNON HOLLAND 


Apple designed the Color Picker Package as a way for applications to present a 
standard user interface for color selection. The goal in developing Color Picker 
version 2.0 was to remain compatible with die existing Color Picker Package while 
providing tighter integration of color pickers wi th the application and allowing 
development of customized color pickers (for example, to support other color spaces 
or specific devices). 

These goals were achieved by adding a Color Picker Manager, turning color pickers 
into components, and separating the color picker components From die Color Picker 
Manager. As components, color pickers are now accessed through the Component 
Manager, which provides a layer between the application and the color picker 
component. In other words, the application calls the Color Picker Manager, which 
thcn calls the C2omponent Manage r, which ca 11 s the color pi cker compon ent. In the 
old Color Picker Package, the application called the color picker directly. 


This separation of the color picker components from the Color Picker Manager 
allows new color picker components to he dynamically added to the system by the 
user or an application. Once a ncw r color picker component has been registered to the 
Component Manager, ids available for use by the Color Picker Manager. 


The interface to the new Color Picker Manager is divided into high- and low-level 
calls: 

* The high-level calls are designed to be used with a minimum of 
fuss, but provide access to nearly the whole feature set available to 
the application through the Color Picker Manager. For 
compatibility with previous versions, the old high-level call, 


SHANNON HOLLAND, once of Apple and 
now starling up something elsewhere, had little 
lime lo write bis bto for this article. His only three 
activities include working, eating, and sleeping. 
Once upon a time he had o life in which he 
enjoyed photography cultural activities, and 
abusing his friends. * 


Color Picker version 2*0 ships with 
QuickDraw GX and also with System 7.5. The 
forthcoming Inside Macintosh: Advanced Color 
imaging will describe Color Picker 2.0 in detail.* 
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GetCoIor, is still there. A new high-level call, PickColor, replaces 
Get Col or and offers a much broader feature set. 

• 1 h e I ow-level ea I Is are designed to a 11 ow ma xi m am fl exi hi I i ty. 

They let the application determine the type of dialog the color 
picker is placed in, rather than using the modal dialog you get with 
high-level calls. The application can also set the current color and 
maintain explicit control over the event loop. Color pickers that 
are invoked through the low-level calls can exist for the life of an 
application. 

This article discusses how to use these calls and take advantage of the new Color 
Picker Manager. The code examples are provided on this issue's CD. Color Picker 2.0 
allows multiple color picker components to exist on a system at one time (through the 
Component Manager). Although the interface for these components is public, this 
article doesn’t discuss the creation of color picker components. 

SPECIFYING COLORS 

Unlike the old Color Picker Package, Color Picker 2.0 uses the more complete 
ColorSync definition of a color, which contains both a color and a profile. The 
profile defines the color space of the color (which includes the type of color—- 
CMYK, HSL, RGB, and so on). You can also specify a destination profile, which 
describes the color space of the device for which the color is being chosen (for 
example, a color printer that will eventually print the document). Given knowledge of 
the destination profile, color pickers that are ColorSync aware can help the user 
choose a color that's within the destination device’s gamut. 

ColorSync is described in ihe forthcoming Inside Macintosh: Advanced Color 
imaging. See also "Print Hints; Syncing Up With ColorSync" in deveiop issue 14,* 

The ColorSync definition for a color, shown below, is used only with the new calls. 
The old call, GetCoIor, still uses RGBColor for compatibility. These structures are 
compatible with QuickDraw GX. 

typedef struct CMFrofile **CMFrofileHandle; 

typedef union { 

RGBColor rgb; 

unsigned short reserved! 4]; 

} CMCoior, *CMColorList; 

typedef struct PMColor { 

CMProfileHandle profile; 

CMCoior color; 

} PMColor, *PMColorPtr; 

If you're specifying an RGB color with no particular profile, you can simply set the 
CMProfileHandle field of PMColor to nil, which uses the system profile. To specify a 
color that uses a profile, you need to provide the profile that describes that color. 


USING THE HIGH-LEVEL CALLS 

The high-level calls are designed to handle the most common uses for the Color 
Picker Manager. The old GetCoIor call provides access to the new dialog and the 
color picker component, but not to any of the new features that are accessible 
through the Color Picker Manager (such as ColorSync colors). 
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The new PickColor call is designed to replace GetColor. It can be used very simply, 
providing roughly die same feature set as Get Color, or it can be used to take 
advantage of some of the more advanced teatures of Color Picker 2.0. 

Hie new r dialog for die high-level calls is much die same as the old one. A new 
button, More Choices, reveals a list of all available color pickers (and changes to 
“Fewer Choices”; see Figure l). Clicking a color picker in the list makes it the current 
color picker for the dialog. Both PickColor and GetColor display this dialog. 



Apple RGB 


Pick a color, any color: 

90° 


180 ° 



Original: 

New: 


Hue Hngle: 
Saturation: 


Lightness: 


31.56 


52.21 


*( 1 ) 


% !±] 


[ Feiner Choices ] 


[ Cancel ] [[ OK j| 


Figure 1. Color picker dialog for high-level calls 


The biggest difference between PickColor and GetColor is that PickColor allows the 
application to provide a pointer to an event filter procedure. If the application 
supplies such a procedure, a movable modal dialog will be created rather than the old 
modal dialog. You can do this from within PickColor because you’re now able to pass 
update events to windows within the same application layer as the color picker. 

PickColor also uses the new Col or Sync color definition, so you can specify a color in 
any color space along with a destination profile. Likewise, a color can be returned in 
any color space. 

PICKCOLOR PARAMETER BLOCK 

Listing 1 shows the parameter block that you pass through to PickColor. The first 
two fields, theColor and dstProfile, are pretty obvious; they’re simply the input (and 
output) color and the profile for the final output device. If there’s no output device, 
you just set dstProfile to nil 

The flags field is a little more complicated. (It’s also used in many of the low-level 
calls.) With PickColor, there are three flags you need to worry about: 

* CanModi fy Palette. If you set this flag, you’re tel 1 ing the color 
picker component that it’s able to install a palette of its own that 
may modify (but not animate) the current color table. If you don’t 
want the colors in your document to change as you make choices 
in the color picker dialog, don’t set this flag. 
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Listing 1. PickColor parameter block 

typedef struct ColorPickerlnfo { 

PMColor 

theColor; 

CMProfileHandle 

dstProfile; 

long 

flags; 

Dialo g P1ac oment Spe c 

piaceWhere; 

Point 

dialogOrigin; 

long 

pickerType; 

UserEventProc 

eventProc; 

ColorChan go dPr o c 

colorProc; 

long 

colorProcData; 

Str255 

prompt; 

Menultemlnfo 

mlnfo; 

Boolean 

newColorChosen; 

} ColorPickerlnfo; 



* Gan Animate Palette. This flag is similar to CanModifyPalette, 
except that it allows the color picker component to modify or 
animate the palette as much as it wants to. 

* AppIsColorSyncAware. 'This informs the Color Picker Manager 
that your application understands CoIorSync colors. This means 
that a color may be returned to you in a different space than the 
one you passed in. For example, you could pass an RGB color 
(with no profile) to the Color Picker Manager and receive back a 
CMYK color (widi its associated profile). If you don’t set this flag, 
the Color Picker Manager automatically converts any color it 
receives hack from the color picker component to RGB space. 

The place Where field tells the Color Picker Manager where to position the color 
picker dialog. The choices are kAtSpedfiedOrigin (at the point specified by the 
dialogOrigin field), kDecpcstColorScreen (centered on the deepest color screen), and 
kCenterOnMa in Screen (centered on the main screen). 

The dialogOrigin field (in conjunction with kAtSpeci Red Origin) is used when you 
request that the color picker dialog be placed at a specific point. When Pick Co I or 
returns, this field contains the location ot the color picker dialog at the time it was 
closed. 

You use die pickerType field to specify the component subtype of the color picker to 
select initially. If you set this field to 0, the default system color picker will be used 
(the last color picker chosen by the user). When PickColor returns, this field contains 
the component subtype of the color picker that w ? as open when the user closed the 
dialog. 

You should set the eventProc field to point to an event filter procedure that w ill 
handle events meant for your application. J f this procedure returns true, the Color 
Picker Manager won’t process the event further. 11 ir returns false, the Color Picker 
Manager will handle the event if it was meant for the color picker. If you set this field 
to nil, a modal dialog will be created (rather than a movable modal dialog). 

The colorProc field can contain a pointer to a procedure that will he called whenever 
the color changes. This allows live updating of colors in application documents as the 
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user selects them. The coIorProcData held contains a long integer that’s passed to the 
color-changed procedure and can be used for any private data. 

The prompt field is a prompt string that the color picker displays to give the user 
some indication as to what the new color is for (for example, a highlight color). 

The minfo field tells die Color Picker Manager what the Edit menu ID is and where 
the various menu items are located within it. 

The newColor Chosen field is set on return from PickColor. If true, it means that the 
user chose a color and clicked OK; otherwise, the user clicked Cancel. 

IMPLEMENTING PIGKCOLOR 

Now lets look at an example of how all this would be used. Listings 2 and 3 show two 
callbacks — the event filter procedure (MyEventProc) and the color-changed 
procedure (MyColorChangedProc). In the color-changed procedure we assume that 
ColorSync is installed. This is because we’ll be setting the AppIsCoIorSyncAware flag 
when we call PickColor, so a non-RGB color might come back from the picker and, 
if so, you need to call ColorSync to convert it to RGB, 

Once you have the two callback procedures, you can go ahead and call PickColor (see 
Listing 4). 

USING THE LOW-LEVEL CALLS 

The low-level Color Picker Manager calls are designed to allow tight integration of 
an application and a color picker (a floating palette, for example). Two features make 
this possible: the application can specify the type of dialog to put the color picker in, 
and the application maintains control over the event loop. 

You can create three types of color picker dialogs with the low-level calls: system- 
owned, application-owned, and color picker-owned. 

* A syytem-owned dialog is exactly like the dialog created by the high- 
level calls — it has OK, Cancel, and More Choices buttons. 

However, with the low-level calls, you can make the dialog modal, 
movable modal, or modeless, 

* An application-owned dialog is actually owned (and supplied) by the 
application. You can use this type of dialog to integrate the color 
picker with other application window features or to extend the 
controls of the color picker. For example, you could add controls 
for altering the style of an object as well as its color. 

* A colorpicker-&wned dialog is created and owned by the color 
picker component itself, which gives that component great 
flexibility because it can determine the size and shape of the color 
picker and the dialog (color pickers in system-owned and 
application-owned dialogs are alw r ays the same size). This is useful 
for implementing floating pickers (such as the color wheel in 
Color MacCheese). 

The application interacts with all three types of dialogs in the same way once they’re 
created. The rest of this section describes how to create each type and then moves on 
to discuss how the application interacts with the color pickers, no matter what type of 
dialog you use. In other w ords, the type of dialog a color picker is in is abstracted 
enough that the application can use roughly the same code to handle all three types. 
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Listing 2* Event filter procedure 
WindowPtr myDocWindow; 

pascal Boolean MyEventProc(EventRecord *event) { 

Boolean handled = false; // Assume we don’t handle the event. 

switch (event->what) { 
case updateEvt: 

// Check to see if the update is for our window, 
if ((WindowPtr) event->mes$age == myDocWindow) { 
DoTheUpdatefmyDocWindow); 
handled = true; 

> 

} 

return handled; 

> 


Listing 3. Color-changed procedure 

pascal void MyColorChangedProc(long userData, PMColorPtr newColor) { 
GrafPtr port; 
eWorld eWorld; 

CMColor color; 

CMError cwError; 

GetPort{Sport); 

SetPort(myDocWindow); 

// Now check to see if the color has a profile. If so, we need to 
// convert it to RGB space, 
if (newColor->profile) { 

// Create a color world and convert the color. This color world 
// matches from the color’s space to the system space (RGB)* 
cwError = CWNewColorWorld(^eWorld, newColor->profile, OL); 
if (cwError == noErr || cwError == CMProfilesXdentical) { 

//We created the color world* Now match the color using a copy 
//so that we don’t munge the original* 
color = newColor->color; 

CWMatchColors(eWorld, &color, 1); 

CWDisposeColorWorld(eWorld); 

> 

} else 

color.rgb ~ newColor->color.rgb; 

// Set the new color and paint the port with it. 
myRGBColor = color.rgb; 

RGBForeColor( SCOlor .rgb); 

PaintRect(fimyDocWindow->portRect); 

SetPort(port); 
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Listing 4. Calling PickColor 

ColorPickerlnfo cplnfo; 

FMColor savedColor; 

// Set the input color to be an RGB color in system space, 
cplnfo.theColor,color.rgb = myRGBColor; 
cplnfo*theColor.profile = OL; 

cplnfo.dstProfile = OL? 

cplnfo,flags = AppIsColorSyncAware | CanModifyPalette l| CanAnimatePalette? 

// Center the picker on the deepest color screen, 
cplnfo.placeWhere = kDeepestColorScreen; 

// Use the default picker, 
cplnfo,pickerType = OL? 

// Install the callbacks, 
cplnfo,eventProc = MyEventProc; 
cplnfo.colorProc = MyColorChangedProc; 
cplnfo,colorProcData = OL; 

strcpy(cplnfo.prompt,"XpChoose a new color"); 

II Tell the Color Picker Manager about the Edit menu, 

cplnfo,mlnfo-editMenuID = kMyEditMenuID? 

cplnfo*mInfo*cutItem = kMyCutltem; 

cplnfo.minfo,copyItem - KMyCopyltem? 

cplnfo.mlnfo.pasteltem = kMyPasteltern? 

cplnfo.mlnfo.clearltem = kMyClearltem? 

cpInfo.minfo,undoItem - kMyUndoItern; 

II Save the current color t in case the user cancels, 
savedColor = cplnfo.theColor; 

11 And finally, pick that color! 

if (PickColorf&cplnfo) == noErr cplnfo,newColorChosen) 

// Go use this new color. Remember it can be in any color space, 
DoMewColorStuff(scplnfo.theColor)? 
else 

II Canceled or an error; restore old color, 

DoNewColorStuff{&savedColor); 

1 


CREATING THE DIALOG 

When creating a system-owned dialog, the application needs to choose whether the 
dialog will be modal, movable modal, or modeless. This is handled by the use of two 
flags: DialoglsModal and DialoglsMoveable. Through obvious combinations of these 
flags, all three dialog types can be created. A nonmovable, modeless dialog (neither 
flag set) is illegal. 

Listing 5 shows the code used to create a modeless system-owned dialog. 
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Listing 5. Creating a modeless system-owned dialog 

SystemDialoglnfo slnfo; 

OS Err result; 

slnfo.flags = DialoglsMoveable + AppIsColorSyncAware + CanModifyFalette 
+ CanAnimatePalette; 

Slnfo,pickerType = OL; 
sInfo.placeWhere = kDeepeslColorScreen; 

slnfo.mlnfo.editMenuID = kMyEditMenuID; 

5lnfo,mInfo,cutItem = kHyCutltem; 
slnfo .mlnfo.copyltem = kMyCopyltem; 
slnfo.mlnfo.pasteltem = kMyPasteltem; 
slnfo,mlnfo.clearltem = kMyCiearltem; 
slnfo,mlnfo.undoltem = kMyUndoItem; 

result = CreateColorDialog(SsInfo, SmyPicker); 


Listing 6 shows how to add a color picker to an application’s own dialog (application- 
owned dialog). 


Listing 6* Creating an application-owned dialog 

DialogPtr myDialog; 

ApplicationDialoglnfo alnfo; 

OSErr result; 

// First create the dialog {make sure it's a color dialog so that the 
// color picker can do all the color stuff it needs to do!), 
myDialog = GetMewDialog(kMyDialogID, nil, (WindowPtr)-l); 

// Set up the ApplicationDialoglnfo structure* 

alnfo*flags = DialoglsMoveable + AppIsColorSyncAware + CanModifyPalette 
+ CanAnimatePalette; 
alnfo.pickerType » OL; 
alnfo.theDialog = myDialog; 

// Put the color picker's origin at (0,0) in the dialog, 
alnfo.pickerOrigin.h = 0; 
alnfo.pickerGrigin.v - 0; 

// Set the Edit menu information, 
alnfo,mlnfo.editMenuID = kMyEditMenuID; 
alnfo.mlnfo.cutltem = kMyCutltem; 
alnfo.mlnfo.copyltem = kMyCopyltem; 
alnfo.mlnfo.pasteltem = kMyPasteltern; 
alnfo,mlnfo.clearltem = kMyClearltem; 
alnfo,mlnfo.undoltem = kMyUndoItem; 

// Finally, add the color picker to the dialog, 
result = AddPickerToDialog{Salnfo, &myFicker); 
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Listing 7* Creating a color picker-owned dialog 

PickerDialoglnfo plnfo; 

GSErr result; 

plnfo,flags = DialoglsMoveable + AppIsColorSyncAware + CanModifyPalette 
+ CanAnimatePalette; 
plnfo*pickerType - OL; 

plnfo,mInfo,editMenuID = kMyEditMenuID; 
plnfo,mlnfo.cutltem = kMyCutltem; 
plnfo,mlnfo.copyltem = kMyCopyltem; 
plnfo,mInfo,paste!tem = kMyPasteltem; 
plnfo,mInfo,clearItem = kMyClearItem; 
pinfo,mlnfo,undo!tern - kMyUndoItein; 

result - CreatePickerDialogf&pInfo, &myPicker); 


Listing 7 shows how to create a color picker-owned dialog. As you can see, the code 
to create all three types of dialogs is nearly identical. Likewise the cade to manage 
them after creation is very similar. Any explicit differences or requirements will be 
pointed out and explained as they're encountered. 

SETTING AND GETTING THE CURRENT COLOR 

One of the most obvious requirements for making a color picker useful is that there 
be a way to set and get the current color. This is very simple. Complexities arise only 
if you need to convert colors from the space they're returned in to a space you can 
understand (such as RGB). 1 he following examples assume you’re familiar enough 
w ith ColorSync to do this (Listing 2 shows how to convert from any space to system 
RGB space), I.Fyou don’t want to deal with diis, don't set the AppIsColorSyncAware 
flag and the Color Picker Manager will automatically convert any color it gets back 
from the color picker to RGB. 

I he concepts of original color and new color have been carried through from the old 
Color Picker Package to the new Color Picker Manager. Simply put, the original color 
is the color that the user is about to change and the new color is t he color to which the 
user changes it. When setting the color for a color picker, you need to set both 
colors. Suppose, for example, that you're writing an object-based paint program and 
have created a floating color picker. When the user clicks an object, you want the 
color picker to show the color of that object. You would do this by setting the original 
color and new color for the color picker to the current color of that object. As the 
user changes the color of the object, the original color would remain the same and 
the new color would change. This gives feedback as to what would happen if die user 
were to cancel the color change. The code to do this is very simple: 

void SetPickerToColor(KGBColor *rgb) { 

PMColor aColor; 

aColor.color.rgb = *rgb; 
aColor.profile = OL; 

SetPickerColor(myPicker f kOriginalColor, saColor); 

SetPickerColor(myPicker , kNewColor, kaCoIor); 

1 
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Whenever the user changes the current color, you need to be able to get the new 
color so that you can update your object accordingly: 

void GetCurrentColor(RGBColor *rgb) { 

PMColor aColor; 

GetPickerColor(myPicker, kNewColor, fiaColor); 

*rgb = aColor.color. rqh; 

) 

Some of you might be saying, “But wait, this example is stupid. Isn’t that what the 
color-changed callback is for?’ 1 The answer is yes, in the modal case, when the color- 
changed procedure is the only way the application knows that the color changed. In 
the modeless case, as we’ll see below in the section “Giving Events to the Color 
Picker,” the application is informed in other ways when the color changes. So in the 
modeless case, you might want to view the colors that the color-changed procedure 
provides you with as temporary colors and not update your internal data until the 
user has actually chosen a color (or at least stopped dragging on a slider). You should 
then make an explicit call to the Color Picker Manager to get the color, and update 
your internal data, 

SETTING THE DESTINATION PROFILE 

If you’re picking a color for an ou tput device for which you have a ColorSync profile, 
you can give this profile to the color picker component so that it can communicate 
the profile’s information to the user (assuming it knows how). You do this with a 
simple call, SetPickerProfile. There’s also a matching call, GetPickerProfile, to get 
rhe current profile from the color picker. It’s important to remember that the 
application owns the memory of any profiles it gives or receives from the color picker. 
When you set the destination profile, the color picker component makes a copy of 
the profile handle; when you get the destination profile, you give the color picker 
component a handle into which it copies the profile data. The following code shows 
how to set and get the destination profile. Setting it is optional; the color picker 
assumes that there’s no profile unless you explicitly set one. 

void SetDestinationProfilefCMProfileHandle profile) { 
if (SetPickerprofile(myPicker, profile) 1= noKrr) 

HandleError(); 

> 

void GetDestinationProfile(CHProfileHandle profile) { 
if (GetPickerProfile(myPicker, profile) != noErr) 

HandleError(); 

} 

GIVING EVENTS TO THE COLOR PICKER 

The basic model for giving events to the color picker is similar to DialogSelect, For 
the most part, you give the event to the Color Picker Manager through the 
DoPickerEvent call. It either handles the event or returns it to the application for the 
application to handle. 

There’s one exception to this rule: menus. If you’ve created a modal system dialog, 
the Color Picker Manager can handle the Edit menu events for you (as it does when 
you call PickCoIor). However, for modeless color pickers there are many menu items 
that the Color Picker Manager has no idea how to handle. If you do send these events 
through to the Color Picker Manager, it will assume all Edit menu selections are 
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meant for the color picker and ignore everything else. Therefore, with modeless 
dialogs, the application needs to he sure to handle its own menu events before calling 
DoPickerEvent. 

You’l I also need to do some extra work in order for the Color Picker Manager to 
handle the Edit menu correctly. If an Edit menu choice will be for the color picker 
(that is, the color picker dialog is ffontmost and the current text item in the dialog 
belongs to the color picker), you need to set up the Edit menu as the Color Picker 
Manager and color picker component want it. To determine how they want the Edit 
menu, call GetPickerEditMenuState. If the user docs choose an Edit menu item, die 
application needs to call DoPickerEdit to tell the Color Picker Manager wfiich edit 
operation to perform. There’s more on this later under “Handling the Edit Menu.” 

Each dine you call DoPickerEvent and the color picker component or the Color 
Picker Manager handles the event, it returns a constant describing what happened. 
There are several possible results, which are listed in Table 1. 


Table 1 » DoPickerEvent return constants 


Constant 

kDidNothing 

kColorC hanged 


kOKHEt 


kCancelHit 


Meaning 

Nothing happened that's worth reporting. 

The user changed the color; you may need to call GetPickerColor to 
get the new color. 

The user clicked OK; returned only by system- or color picker-owned 
dialogs. 

The user clicked Cancel; returned only by system- or color picker- 
owned dialogs. 


kNewPiekerChosen The user chose a new color picker From the More Choices list; returned 

only by system-owned dialogs. 

kApplltemHit The Dialog Manager returned an item intended for one of the 

application's dialog items; returned only by application-owned dialogs. 


Internally, the Color Picker Manager handles the event by calling DialogSelect and 
then processing the event from there. Tf the color picker is in an application dialog 
and an application item is selected, the Color Picker Manager returns kApplltemHit 
as well as the item number. 

There are a few things to keep in mind regarding the DoPickerEvent return 
constants, 1 low you handle kColorChanged with application dialogs depends on your 
application; for system-owned and color picker-owned dialogs you probably should 
wait until the user clicks OK before treating the color as final. With kOKHit, you 
should save the new' color and close the dialog. With kCancell lit, you should restore 
the old color and dispose of the color picker. If kApplltemHit is returned, you need 
to handle the event as you would for the Dialog Manager. You don’t need to care 
about kNewPickerChosen, which happens only w'ith a system-owned dialog. 

If you have a color-changed procedure for the color picker to call, you supply the 
procedure, along with any data it needs to be called with, to DoPickerEvent. 
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Listing 8 shows w r hat your event loop might look like. In this code we assume that 
you always want to handle the menu events yourself, as discussed above. 





Listing 8* Sample event loop 


^define IsMenuKey(x) [(x)~>what == keyDown && [x)->modif'iers & cmdKey) 
Boolean SampleDoEvent(EventRecord *event) { 

Boolean handled = false, isMenuEvent = false? 

EventData pEvent; 
short inWhere; 

WindowFtr whichWindow; 


// We are assuming that the application always wants to handle menus, 
if (event->what == mouseDown) { 

inWhere = FindWindow(event->where, kwhichWindow); 
if (inWhere == InMenuBar) 
isMenuEvent = true; 

> 

if (isMenuEvent | | IsMenuKey(event J) { 

DoMenufevent}; 
handled = true; 

} 

//If the event's not handled yet, call the Color Picker Manager to 
// give it a shot, 
if (Ihandled} { 

pEvent.event = event; 

pEvent.colorProc = MyModelessColorChangedFroc; 
pEvent.colorProcData = OL; 

DoPickerEvent(myPieker, &pEvent); 
handled = pEvent.handled; 

// If the color picker handled it, we might want to do something 
// with the results, 
if (handled) { 

switch (pEvent.action) { 
case kDidNothing: 
break; 

case kColorChanged: 

UseNewColor(myPieker); 
break; 

case kOKHit: 

UseNewColor(myPieker); 

DisposeColorPicker(myPieker); 

myPieker = nil; 

break; 

case kCancelHit: 

UseOriginalColor(myPieker); 

DisposeColorPicker(myFicker); 

myPieker = nil; 

break; 

case kNewPickerChosenr 

// You shouldn't care about this, 
break; 


(continued on next pagej 
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Listing 8, Sample event loop (continued) 
case kApplItemHit: 

// Handle the item as you would for the Dialog Manager, 

HandleAppItem(pEvent.itemHit}; 

break; 

} 

> 

} 

if (Jhandled) { 

// The event hasn't been handled. Treat it as you would any normal 
// Macintosh event. If you have other dialogs, you need to call 
// DialogSelect, Remember, if the event is a mouseDown, you 
// already called FindWindow! 

} 

return handled; 


FORECAST EVENTS 

When dealing with a color picker, you’ll sometimes need to warn it about a user 
action that might affect it. For example, if you have a color picker in an application 
dialog and the user closes that dialog, you might want to see if the color picker is in a 
state that can handle this. If the user had just typed some numbers into the color 
picker that left it in an inconsistent state, it would be nice if the color picker could 
have a chance to complain to the user before it was indiscriminately closed. 

You can do this by using forecast events. These aren’t really events in themselves, but 
are warnings to the color picker* To send forecast events to the color picker component, 
you use the same call as for regular events — DoPickerEvent — except that you set 
the event field to nil and set the forecast field to an appropriate constant* The color 
picker component tells you w hether it’s ready for the action to occur by setting the 
handled field of the EventData structure to true if it’s not ready and false if it is* 

For the most part, the only time your application needs to worry about this is when 
the color picker is about to be closed. If the Color Picker Manager has instigated the 
closing (such as when the action field is set to kOKHit after you called DoPickerEvent), 
you don’t need to worry about telling the color picker component because the Color 
Picker Manager has already done so* However, if the user has just clicked the 
window’s close box (for an application dialog) or has chosen Close from a menu, you 
should send a forecast event to the color picker component. 

The following example shows a function called ChecklfPickerCanClose* If this 
function returns true, the color picker can close; otherwise, it can’t close for some 
reason* IPs safe to assume that die color picker has informed the user of the problem. 

Boolean CheckIfPickerCanClose(} { 

E ve nt Data pEven t; 

pEvent.event = QL; // Make it a forecast event. 
pEvent.forcast = kDialogAccept; 

DoPicke rE vent(myPieke r, & pEvent); 

return l pEvent*handled; 

} 
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HANDLING THE EDIT MENU 

As mentioned earlier, the Edit menu takes some special work In addition to standard 
menu processing, if an Edit menu choice will be for the color picker, you need to set 
the state of the Edit menu items according to the color picker specifications and, if an 
Edit menu item is chosen, send the appropriate message to the color picker* This is 
done through two simple calls: GetPickerEditMenuState and DoPiekerEdit. 

Once you've determined that there has been a mouse-down event in die menu bar or 
a keyboard equivalent has been pressed, you need to determine who owns the Edit 
menu. If the color picker is in a color picker-owned or system-owned dialog and ids 
frontmost, the color picker obviously owns it. If the color picker is in an application- 
owned dialog and ids frontmost, ownership of the Edit menu depends on the current 
item. The choice really depends on your application. As a general rule, whoever owns 
the current item owns the Edit menu. If you do call DoPiekerEdit while the current 
item belongs to your application, it will implement the standard cut, copy, paste, and 
clear features for you. If your application needs to do more than this, you'll need to 
handle it yourself. 

In Listing 9 we assume that the owner of the current item owns the Edit menu. The 
item number for the application's last dialog item is kMyLastltem. If you have a 
system-owned or color picker-owned dialog, this constant should be set to 0. Ln an 
application-owned dialog the picker's items will always be added after the 
application's, so your item numbers remain the same. 


Listing 9« Handling the Edit menu 

Boolean DoMenufEventRecord *event) { 
long mChoice; 

EditData sData? 

E ditOpe r ation eQpe r ation; 

//if picker is in front and current edit item is the pickets, 

// set up the Edit menu the way the picker wants it, 
if (Frontwindowf) == myDiaiog && 

((DialogPeek)myDialog)->editField + 1 > kMyLastltem) { 

MenuState mState; 

MemiHandie theMenu; 

GetPickerEditMenuState (myPicker, fcmState) ; 
theMenu = GetMenu(kMyEdltMenuID}; 
if (instate.cutEnabled) 

EnableItem(theMenu, kMyCutItem); 
else 

Dis ableItem(theMenu , kMyCutltem); 
if (mState,copyEnabied} 

EnableItem(theMenu, kMyCopyltem); 
else 

Disableltem(theMenu, kMyCopyltem); 
if (mState.pasteEnabled) 

Enableltem(theMenu, kMyPasteltem); 
else 

Disableitem(theMenu, kMyPasteltem); 

(continued on next page) 
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Listing 9* Handling fhe Edit menu (continued) 

if (mState.clearEnabled) 

Enableltem(theMenu, kMyClearltem); 
else 

DisableltemftheMenu, kMyClearltem); 
if (instate. undoEnabled) { 

Setltem(theMenu, kMyUndoItem, mState.undoString); 

EnableIten(theMenu, kMyUndoItem); 

} 

else 

Disableltem(theMenu, kMyUndoItem); 

> 

// Give the event to the Menu Manager* 
if (event->what ** mouseDown) 

mChoice * MenuSelect(event->where); 
else 

mChoice “ MenuKey(event->message); 

//If not the Edit menu, handle normally, 
if (HiWordfmChoice) 1= kMyEditMenuID) { 

HandleMenuChoice(mChoice); 
return true; 

} 

switch (LoWord{mChoice)) { 
case kMyCutltem; 

eOperation = kCut; 
break; 

case kMyCopyltem; 

eOperation = kCopy; 
break; 

case kMyPasteltem: 

eOperation - kPaste; 
break; 

case kMyClearltem; 

eOperation * kClear; 
break; 

case kMyUndoItem: 

eOperation = kUndo; 
break; 
default: 

eOperation = -1; 
break; 

> 

if (eOperation >= 0) { 

eData.theEdit = eOperation; 

DoPiekerEdit(myPicker, SeData}; 

// Ignore the results here; assume that the color changed. 
UsetfewCo lor (myPicker}; 

> 

HiliteMenu(0); 
return true; 
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USING BALLOON HELP 

The Color Picker Manager provides support for Balloon Help, Most applications 
don’t need to do anything special for Balloon Help to work for a color picker in any 
type of dialog* However, for applications in which you need more control over 
Balloon Help, you can call ExtractPickerHelpItem to get the balloon for the color 
picker. It's up to the application to determine whether the cursor is over a color 
picker’s item or one of its own. The best way to do this is to check to see if it’s over 
one of the application items. If so, put up your own balloon; otherwise, call 
ExtractPickerHelpItem and put up the balloon it returns. ExtractPickerHelpItem will 
ask the color picker for a balloon and search the color picker’s help resource for an 
appropriate balloon. If it can’t find one, it returns the error nolle lpFor I tern. 

The hardest part about using ExtractPickerHelpItem is determining which item the 
cursor is over. Fortunately, there’s a Dialog Manager call, FindDItem, that does the 
dirty work for you. Listing 10 shows how you would use these calls. Everything in 
this example is actually done by the Color Picker Manager internally; the example 
just gives you a general idea of how to use the ExtractPickerHelpItem call. 


Listing TO, Using ExtractPickerHelpItem 

void DoBalloonHelp(void) { 

Helpltemlnfo helplnfo; 
short itemNo; 

Point where; 

OSErr err; 

GetMouse(&where); 

itemNo = FindDItem(myDialog, where) + 1; 

//Go and get the color picker's help item. 

helplnfo.options = 0; 

helplnfo.tip.v = helplnfo.tip.h = 0; 

SetRect(Shelplnfo.altRect, 0, 0, 0, 0); 
helplnfo.theProc = 0; 
helplnfo.variant = 0; 
helplnfo.helpMessage.hmmHelpType = 0; 
helpInfo.helpMessage.u.hmmPictHandle = 0L; 

err = ExtractPickerHelpItem(myPicker, itemNo, 0, khelplnfo); 

// Show the balloon if we found one. 
if (err — noErr) { 

// If altRect is empty, we need to use the item's rectangle, 
if (EmptyRect(&helplnfo.altRect)) { 
short iType; 

Handle iHandle; 

GetDItem(myDialog, itemNo, &iType, siHandle, &helplnfo.altRect); 

} 

// Convert the tip to dialog coordinates, 
helplnfo,tip.h += helplnfo,altRect.left; 
helplnfo,tip,v += helplnfo,altRect.top; 

(continued on next page) 
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Listing 10 . Using ExtractPickerHelpItem fconf/rnredj 

// Convert the tip and altRect to global coordinates. 
LocalToGlobal(fihelplnfo.tip); 

LocalToGlobal((Point *) fchelprnfo. altRect .top) - r 
LocalToGlobal((Point *) shelpinfo.altRect.bottom ); 

if Finally, put the balloon up, 

HMShowBalloon(ahelpinfo.helpMessage, helpinfo.tip, 

&helpinfo.altRect, OL, helpinfo.theProc, helpinfo.variant, 
kHMRegularWindow); 

> 

} 


TAKE YOUR PICK 

You should now have a general idea of how to use the new Color Picker Manager* 
Most applications will need only the high-level calls. However, developers who use 
color more thoroughly may want to take advantage of the low-level calls. The 
low-level calls were designed to be very flexible and easy to use* The simple 
implementations shown in this article are trivial; more complicated uses are possible, 
and shouldn’t be much harder to write. 

Having experimented with the new features of Color Picker 2*0, you may still want to 
write your own color picker component — for example, to implement your own 
floating color picker. The new Color Picker Manager makes it easier for you to write 
your own color picker component and allows you to share it among several 
applications (and make it available for general system use as well). 

So take your pick of the color pickers already available through the high-level or low- 
level calls or move beyond this article to create your own custom color picker 
component. Either way, you Ye looking at a colorful future with Color Picker 2.0. 
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SOMEWHERE IN 
QUICKTIME 

Media Capture 
Using the 
Sequence Grabber 


A very important and often overlooked feature of 
QuickTime is the standardization of media capture. 
Since its initial release, QuickTime has defined an API 
for capturing different types of media, including video 
and sound. This API, biown as the sequence grabber, 
makes it possible to easily add media capture to any 
application. 

Not only are applications that use the sequence grabber 
able to automatically support any QuickTime- 
compatible media capture hardware, but they also 
perform flawlessly and efficiently regardless of system 
configuration, This is not an easy task considering all 
the variations in hardware features and system 
configurations. In fact, weVe even hesitant to say that 
the sequence grabber “supports video and sound 
capture” because the sequence grabber API also 
insulates the programmer from the actual media type 
being captured. The sequence grabber supports any 
media type, and, with the release of QuickTime 2.0, 
users can automatically capture the new music media 
type in addition to sound and video. 

To demonstrate the proper use of the sequence 
grabber, weVe included on this issue’s CD a simple, but 
complete, sequence grabber application — all in about 
1QK of compiled C code! If you’re looking for a general 
all-purpose capture application that’s efficient, reliable, 
and best of all, customizable, look no further. After a 
brief introduction to the sequence grabber, we’ll discuss 
the sample code, and then end with some special 



considerations for media capture on Macintosh AV 
models. 

WHAT IS THE SEQUENCE GRABBER? 

The sequence grabber is actually a component of type 
barg 1 (read it backwards). Although the specification 
for the component is completely defined in Chapter 5 
of Inside Macintosh: QuickTime Comp orients, it’s very 
unlikely that you’ll ever want to implement your own 
barg 1 component. Instead, you’ll be using this 
component specification as the API definition for the 
standard sequence grabber. 

The sequence grabber component implements the 
basic functionality of media capture. For handling 
specific media-related functions, the sequence grabber 
calls on various sequence grabber channel components 
(as defined in Chapter 6 of Inside Macintosh: QuickTime 
Components)] there’s one such component for each 
media type. Before QuickTime 2.0, the two standard 
channel components available were the video and 
sound sequence grabber channels, enabling the 
sequence grabber to capture video and sound media. 
QuickTime 2.0 includes the new music sequence 
grabber channel, allowing real-time capture of music 
from MIDI instruments. 

Sequence grabber panel components (described in 
Chapter 7 of Inside Macintosh: QuickTime Components) 
manage items in a settings dialog box that allows the 
sequence grabber to obtain configuration information 
from a user. Applications typically don’t use sequence 
grabber panel components directly; instead, the 
sequence grabber automatically uses them for relevant 
sequence grabber component calls. 

USING THE SEQUENCE GRABBER 

Using the sequence grabber is as simple as opening the 
sequence grabber component and calling SG Initialize 
(complete error checking can be found in the sample 
code on the CD): 

theSG = 

OpenDefaultComponent(SeqGrabComponentType, 0); 
SGInitialize(theSG); 


JOHN WANG (AppleLink WANGJY) While writing the 
sequence grabber sample code For this column, John watched the 
movie Fop Gun so many times that he can now duplicate each and 
every air combat scene with his favorite flight simulator, FA/18 
Hornet. John once aspired to become a private pilot, but that idea 
was quickly quelled once his significant others found out. As Skate 
so succinctly put it, "Woof woof wooof?" Translation: "'Who's 
going to feed me if you kill yourself?""* 


FERNANDO ("NANO"} URBINA (AppleLink NANO) uses his 
Macintosh AV to capture the views of the Rockies from his home 
office in Colorado Springs, He still doesn't understand how it can 
thunder and snow at the some time, but thinks hell be able to 
figure this out once he adjusts to the lack of oxygen. Nano suffers 
severe withdrawal from his favorite coffee shop neor the Apple 
campus in Cupertino, but manages to get a fix about once a 
month when he returns there. He worked on the original AV 
models and is now a member of the second-generation AV team.* 


SOMEWHERE IN QUICKTIME: MEDIA CAPTURE USING THE SEQUENCE GRABBER 85 








It's also i mportant to call SGSetGWorld to set die 
window used lor displaying any visual data. 

SGSetGWorld((**myWindowInfo)*theSG, 

(CGrafPtr) myWindow, nil); 

Opening the channel components* Now ids a 

matter of calling SGNewChannel to open a sequence 
grabber channel component to access a particular 
channel media type. However, rather than hard-coding 
die media types into the sample application, as in die 
call 

SGNewChanne1(theSG , VideoMediaType, 

ScvideoChannel); 

ids better to use the Component Manager to search lor 
all the different sequence grabber channel components 
and open a connection to each one* This guarantees 
that the capture application can automatically support 
new media types such as the music media type in 
QuickTime 2*0. 

For example, the following code compiles a list of 
sequence grabber channel components: 

cd*componentType = SeqGrabChannelType; 
cd* componentSubType = 0; 
c d * c ompo ne ntMan u f acta rer = 0; 
cd.componentFlags = 0; 
cd.compcmentFlagsMask = 0; 

^Component = 0; 

for (i=Q, done=false; i<kMAXCHMNELS £& !done; 

i++) { 

aComp = FindNextComponentaComp, Scd); 
if (aComp !- 0) { 

// Get the channel name and type* 
gSGInfo*channelName[i] = UewEJandle(4); 
GetComponentInfo(aComp, &theCD, 

gSGXnfo*ehannelName[i], nil, nil); 
gSGInfa.cftannelTypefi] = 
theCD,componentSubType; 

} else 

done = true; 

} 

This list of component types can then be used to open 
a connection to each of the media types with 
SGNewChann el, or SGNewChannelFrom Component 
if the channel component is already open. 

Saving and restoring settings* We want die sample 
application to start up each time with the same channel 
settings and video compression settings as when the 
application Mas last used* To implement this, we use a 


preferences file to store these settings. The 
compression settings are restored with two sequence 
grabber calls: 

SGSetVideoCompressorType( 

(**myWindowInfo).channel[videoChanneI], 
gSGInfo.cInfo * compres sorType); 

SGSetVideoCompressor( 

{* *myWindowInfo)* channel[videoChannelJ , 
gSGInfo.clnfo.depth, nil, 
gSGInf o * clnfo.spatialQuality, 
gSGInf o * clnfo * temporalQuality, 
gSGInfo * clnfo * keyFrameRate); 

'The channel settings are restored by a simple call to 
SGSetChannelSettings with the settings retrieved from 
the preferences file: 

SGSetChannelSettings[theSG, channelfi], 
channelSettings[i], 0); 

Previewing* We're almost ready to begin previewing* 
But note that some sequence grabber channel 
components require additional calls before they can be 
used. For instance, spatial channels such as video 
require a call to SGSetCliannelBounds to set the 
channel's display boundary rectangle. So, once the 
channels are created and the previous settings are 
restored as discussed above, we make a call to 
SGSetChannelBounds for the video media to set the 
video Capture to encompass the entire window. We also 
call SGSetCh arm el Usage for all sequence grabber 
channels, which tells the sequence grabber that we 
want to preview and record every channel. 

To start previewing, we simply call SGStartPreview. 
However, while we're previewing, any changes to the 
system must be handled with care. First, we'll pause the 
preview whenever an event that requires updating of 
the channel information occurs* For example, if the 
capture window is dragged, we'll pause the video, 
move the window, and then unpause the video. 

Li kew i se, if w e r esi ze the wi n d ow, w ell wa n t to pa us e 
the preview, resize the window, and then unpause the 
preview: 

// Pause the sequence grabber before resizing* 
SGPausef{**myWindow!nfo)*theSG, true); 

// Resize and then update the video channel. 
SiseWindow(theWindow, width, height, false); 
MyUpdateChannels(theWindow); 

// OR* We can restart again* 

SGPause((**myWindowlnfo)* theSG, false); 
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Notice the call to MyUpdateChannels. This is a 
routine in the sample application that updates the 
video bounds and channel usage by calling 
SGSetChannel Bounds and SGSetChannelUsage, 

The user configuration dialog. Another feature that 
needs to be handled in a capture application is the user 
configuration dialog for each of the different capture 
medias, This is actually one of the simplest tilings to 
deal with because the sequence grabber component 
handles everything. It even stores the settings 
internally. To retrieve the settings, we can simply call 
SGGetChannelSettings at a later time. In the sample 
application, we get the channel settings before we close 
the connection to the sequence grabber. Then we save 
the settings in the preferences file. 

This is all the code necessary to display and handle the 
user configuration dialog: 

SGSettingsDialog{theSG r theChannel, Q f nil, G r 

nil, 0); 

Recording. The last important part of the sample code 
is sequence grabber recording. Before recording can 
begin, we need to specify an output file with 
SGSetDataOutput so that the sequence grabber knows 
where to save the captured media data: 

StandardPutFile( n \PName of new movie:", "\pMovie", 
&reply); 

if (!reply,sfGood) 
return; 

SGSetDataOutput(mySG, &reply.s f File, 
seqGrabToDisk); 

Then we start recording by simply calling 
SGStartRecord(theSG); 

We loop and call SGIdle until die mouse button is 
pressed to stop recording. This is the most efficient 
way to record: we don’t want to cal! WaitNextEvent, 
since that would give other processes time. Instead, we 
want to hog the CPU time until die recording process 
is done, 

while (!Button() && ierr) { 
err = SGIdle(theSG); 

We stop recording and start previewing again as 
iollows: 

SGStop(mySG); 

SGStartPreview((**myWindowInfo).theSG); 


And, of course, just to be nice, we flush the mouse¬ 
down events so that no application switching takes 
place after the mouse button is pressed: 

FlushEvents(mDownMask, 0); 

That’s really all there is to the sequence grabber sample 
application. 

SPECIAL CONSIDERATIONS FOR AV MODELS 

As mentioned earlier, one of the key features of the 
sequence grabber is its ability to work with al! hardware 
and system configurations. This is not an easy task 
ct>nsi d e ring a 11 th e d ifferent type s o f v i d eo ca pture 
boards. For example, there are boards that are simply 
frame grabbers, and there are those that support on¬ 
board hardware video compression. To make every 
configuration work, the sequence grabber has to handle 
every case. Here well discuss the unique features of the 
Macintosh AV models and some steps you can take to 
improve their capture rate. 

The video-in circuitry allows the AV models to display 
16-bit color and 8-bit grayscale. And, although the 
hardware can’t display video-in at 24 bits per pixel, you 
can capture video using YUV 4:2:2 compression and 
achieve an effective 24 hits per pixel. To capture in 
YUV, you must use the AV’s video digitizer hardware 
compression feature, which you can do simply by 
selecting “Component Video - YUV” from die list ol 
compressors in the Compression panel ol the video 
settings dialog. You should also make sure that you 
haven’t checked a “Post Compress Video” or similar 
checkbox in a movie-grabbing application. Selecting 
this checkbox would bypass the hardware compression, 
and the sequence grabber would grab the data in raw 
RGB format. 

The AV circuitry can’t display video when it’s capturing 
the compressed data. The sequence grabber realizes 
that it needs to decompress the data into the capture 
window in order to give the visual feed!jack that’s 
normally expected. This is fine and dandy, but since 
there’s no hardware decompression in the system, the 
image decompression is completed in software. This 
degrades the capture rate. 

Knowing diat the decompression during recording is 
what’s hurting the capture rate, you can easily rectify 
the problem by turning off preview during recording so 
that decompression into the capture window won’t take 
place. To do this, you just call SGSetChannel Usage for 
the video channel with the seqGrabPlayDuringRecord 
flag set to 0. In the sample code, a menu selection 
allows you to turn off video pi ay through during 
recording. 
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The downside of using YUV compression is that 
playback without hardware decompression isn't very 
smooth because of the high data rate and raw 
processing power needed to decompress each pixel. 
After capturing, you should re compress the movie 
using a compressor such as Cine pa k or Video tli at 
provides a better playback rate. 


channel. For example, you can record video to a large 
and fast external hard drive and record audio to the 
internal hard drive. This optimization allows for better 
allocation of resources and better efficiency because 
each channel has higher bandwidth. Using the sample 
code, if QuickTime 2.0 is installed, you can select 
recording to separate files. 


GO MAKE A MOVIE 

The sequence grabber obviously makes the job of 
media capture simpler. But there are many other 
factors that can play a part Hard drive transfer rate, 
disk fragmentation, SCSI bandwith, sound settings, and 
AppleTalk activity all play an important part in limiting 
the maximum capture rate. You can also maximize the 
capture rate by rebooting with no AppleTalk 
connections. You should also experiment with the 
different sound sample rates, as these also affect the 
capture rate. 

New additions to the sequence grabber in QuickTime 
2.0 also help. Instead of capturing to a single movie file, 
it's now possible to specify a different file for each 


There are, of course, other optimizations that can be 
explored. With a bit of creativity and testing, you can 
achieve the optimal capture rates. 


RELATED READING 

* Inside Macintosh: QuickTime Components , 
Chapters 5-7, and Inside Macintosh: More 
Macintosh Toolbox, Chapter 6, "Component 
Manager" [Addisan-Wesley 1993). 

* "Video Digitizing Under QuickTime" by Casey 
King and Gary Woodcock, develop Issue 14. 
About the sequence grabber and video capture. 


Thanks to Peter Hoddie and Don Johnson for reviewing this 
column.* 
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Implementing Inheritance In Scripts 


“Programming for Flexibility: The Open Scripting Architecture” in 
develop Issue 18 showed you how to use scripts to increase your 
program's flexibility. This article builds on that one and explains how to 
implement an inheritance scheme in your application that will enable 
your AppleScript scripts to share handlers and properties and to support 
global variables. You 'll also learn, a way to support inheritance in other 
OSA languages with just a little extra work. 



PAUL G. SMITH 


In Issue 18 of develop, I showed you how to attach scripts to application-domain 
objects and how to delegate the handling of Apple events to those scripts. 1 left you 
with a challenge: to figure out how to support global variables and to enable scripts to 
share subroutines and handlers. To meet this challenge you need to implement 
inheritance. The AppleScript 1.1 API gives you all the necessary calls to implement 
inheritance in embedded AppleScript scripts, but not all are documented yet in Inside 
Macintosh, This article documents the calls you need and describes an inheritance 
scheme that relies on them. 

In a nutshell, here’s the scheme: 

1. Decide what kind of script inheritance hierarchy to use, 

2. Link your scripts together in an inheritance chain, 

3. Create a shared handlers script to define subroutines and Apple 
event handlers that are shared among all scripts. Make this script 
the parent of all other scripts in your program, in effect putting it 
at the end of the inheritance chain. 


4. Create a global variables script and add this to the start of the 
inheritance chain so that it’s the first script to receive incoming 
messages. Save this script to disk when die program exits and 
reload it when the program restarts, so that variables persist. 


You can use much the same scheme to implement inheritance in other Open 
Scripting Archi tecture (OSA) languages, but more work is required to link scripts 
together in an inheritance chain, and you must forgo the luxury of sharing global 
variables between scripts. At the end of this article, the section “Inheritance in Odier 
OSA Languages 75 describes the extra work your program must do. 


PAUL G. SMITH (AppleLink COMM STALK. HQ] 
took lime out from his preferred occupation of 
snoozing on a beach to write this article. He also 
occasionally takes time out to write software for 
Full Moon Software Inc., provide consultancy 


services to corporate clients, and watch his cat, 
Mack, dismember his Macintosh's mouse. He was 
the lead developer of AgentBuiider and wrote 
SeriptWizard, the AppleScript debugger, before 
he found his true, totally prone, calling.* 
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Th e sain pi e p rogra in Si rn p 1 i F a ce 2 o n th is i ssu e f s CD de mons tra te s the inheri van ce 
mechanisms discussed here, ShnpliFace2 is an extension of SimpliFace, the basic 
interface builder used to illustrate the article in Issue 18. The SimpliFace2 sample 
code has a compile-time flag qUseOSAinheritance, defined in the header file 
SimpliFace2Common.h. If this flag is undefined, the program uses the AppleScript- 
specific inheritance scheme described in die bulk of this article. If the flag is defined, 
SimpliFace2 uses a general-purpose scheme that involves the extra work outlined in 
the section on inheritance in other OS A languages. 

CHOOSE A SCRIPT INHERITANCE HIERARCHY 

The first thing to do is to decide what kind of script inheritance hierarchy to use. You 
can use a runtime containment hierarchy (like that used by HyperCard and FaceSpan™), 
a class hierarchy (like that used by AgentBuilder), or some hybrid of the two, as 
demonstrated by SimpliFace2. Let’s look at each of these hierarchy types in turn. 

FaceSpan (formerly Frontmost) Is the interface builder bundled with the 
AppleScript 1.1 Software Development Toolkit. Perhaps the best known OSA "client/' 

FaceSpan was developed by Lee Buck (of "WindowScript" fame) of Software Designs 
Unlimited, Inc. AgentBuilder, from commstalk hq and Full Moon Software Inc., is □ 
framework for the creation of communications and information-processing agents that 
uses embedded OSA scripts to customize agent behavior.* 

Figure 1 shows a runtime containment hierarchy. In this kind of hierarchy, objects 
inherit behavior from their containers ar run time. In the object containment 
hierarchy used by HyperCard, for example, the scripts of buttons and fields within 
cards are at the bottom of the hierarchy. Above them are the scripts of the cards that 
contain the buttons and fields, and above each card script is the script of the 
background that contains the card. Above each background script, in turn, is the 
script of the stack that contains all the backgrounds. The handlers in each container's 
script are shared by the scripts of all the objects it contains. 

Figure 2 shows a class hierarchy. In this kind of hierarchy, objects inherit behavior 
from their parent classes. For instance, the behavior of AgentBuilder objects is 
defined in an “ancestor” object of each class, which is the parent of all instances of 
that class. This permits die standard scripted behavior of object classes to he 
overridden in derived class instances. 



Default behavior 
in Apple event 
handler code 



Figure 1* A runtime containment hierarchy 


Figure 2. A class hierarchy 
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Figure 3 shows the hybrid script inheritance hierarchy used in SimpliFace2. In 
SimpliFace2, the scripts of user-interface objects — such as windows, labels, and 
buttons — are organized so that they inherit behavior from the runtime containment 
hierarchy. However, the script of the application object isn’t included in the 
inheritance chain for the script of any user-in ter face object, and the shared handlers 
script becomes the ultimate parent of all other scripts, I chose to use this hybrid 
hierarchy in order to demonstrate a wider range of techniques, not for any reason 
intrinsic to the program design. 



Figure 3. The hybrid script inheritance hierarchy used in SimpliFace2 

The kind of script inheritance hierarchy to use depends on the nature of the messages 
being handled in your program. Using a class hierarchy is most appropriate if the 
messages are Apple events defined in the program’s 'aete' resource. If the incoming 
messages are primarily user-defined subroutines being handled inside scripts, using a 
runtime containment hierarchy is probably more natural for the scrip ter. 

Another way to look at this choice is that if you want to enable users to customize 
your program’s capabilities by attaching scripts to application-domain objects, using a 
runtime containment hierarchy isn’t always the best idea. Because different 
application-domain objects handle the same Apple event message in different ways {in 
other words, the semantic meaning of the message differs depending on what object 
it’s directed at), unwanted side effects could result from an object’s handling an Apple 
event message intended for a different level in the containment hierarchy. Using a 
class hierarchy ensures that messages will be dealt with only by objects of the class 
that understands them. 

Once you’ve chosen the type of script inheritance hierarchy most appropriate for 
your program, you can link scripts together in an inheritance chain. 

LINK SCRIPTS IN AN INHERITANCE CHAIN 

Linking scripts together in an AppleScript inheritance chain is as simple as setting 
their parent properties. Before I tell you how to do that, though, let’s review a lev' 
facts about script objects and inheritance. As mentioned in the Issue 18 article, a 
script context (a script compiled using the AppleScript OSA component) is equivalent 
to a script object in the AppleScript language, so everything I say here about script 
objects applies to script contexts as well, 

ABOUT APPLESCRIPT SCRIPT OBJECTS AND INHERITANCE CHAINS 

Script objects can contain global variables, properties, and handlers for Apple event 
messages and subroutine calls. A script object can have as its parent property an 
object specifier or another script object. Thus, one script object can become the 
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parent of another, and the child script object can inherit properties and handlers from 
the parent script object. Parent and child script objects are linked together in an 
inheritance chain; this is the path from child to parent to grandparent and so on in an 
inheritance hierarchy, as illustrated in Figure 4. 

For (a lot) more on object specifiers/ see "Apple Event Objects and You" by 
Richard Clark in develop Issue 1G. # 



Start of chain 


Figure 4- A script inheritance chain 

An incoming Apple event message is received by die child script object at the start of 
the inheritance chain* If AppleScript can't resolve a reference to a handler or variable 
name within this script object, it searches through the entire inheritance chain to find 
it* The handler or variable is resolved wherever it's found in the inheritance chain. 
When a handler continues a message (that is, passes the message to its parent), 
AppleScript starts searching in its parent script object Messages that target objects 
outside the program’s domain, or diat aren’t handled anywhere in the script 
inheritance chain (such as Apple events defined in the program’s ’aete' resource, 
which are handled in die program code instead), or that are continued out of the 
inheritance chain, are redispatched as Apple events, 

SETTING A SCRIPT'S PARENT PROPERTY 

Now that you understand the dynamics of script inheritance. I’ll show you how to set 
a script’s parent property and thus link it to an inheritance chain. In the AppleScript 
language, you simply say what you’d like the parent set to, as illustrated here: 

script mom 
on getName() 

return "Fenella" 
end getName 
end script 

script toddler 

property parent ; mom 
on getName () 

set myMom to continue getName() 
return "Bart, son of u & myMom 
end getName 
end script 

getName() of toddler —> returns "Bart, son of Fenella" 
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To set the parent of a script context from a programming language, you can use the 
AppleScript routine OSASetProperty. This general-purpose routine (defined in the 
header File ASDebugging.h, which was added with the AppleScript i.l API) accesses 
either a predefined property or a user-defined variable, depending on the AEDesc 
passed to it. To access a predefined property — the parent property — you create a 
descriptor of typeProperty (not typeType), specifying the property ID as the data. 

The parameters to the call are (1) the scripting component (probably the AppleScript 
component), (2) a mode flag (we use the null mode, indicating no special action 
should be taken; alternatively, we could instruct AppleScript to replace the property 
only if it already exists), (3) the script context ID that's to he changed, (4) the 
AEDesc, and (5) the value youVe setting the property to, in our case the new parent. 
The OSA routine OSAGetProperty performs the converse function: you can use it to 
inspect die values of properties and variables. 

Here's a fragment from SiinpIiFace2 that sets the parent of a script by calling 
O S AS e tP roperty: 

OSAError err ~ noErr; 

AEDesc nameDesc; 

DescType thePropCode = pASParent; 

err = AECreateDesc{typeProperty, (Ptr)SthePropCode r s1z eof(thePropCode), 

&nameDesc ); 

if (err == noErr) ( 

err = OSASetProperty(scriptingComponent, kOSAModeNull, contextID, 

SnameDesc, newParentID); 

AEDisposeDesc(SnameDesc); 

> 

The structure of the inheritance chain is static; each parent link needs to be set up 
only once, as long as no scripts are replaced. The only exception to this is that the 
parent property of the global variables script used in SimpliFace2 needs to be set 
every time an incoming Apple event message is handled, as Ell explain later. 
Whenever a script in the chain is replaced by a new one, the script's OS AID will 
change and you'll need to set the parent property in the new script and in its children 
again* 

STRIPPING COPIED PARENT SCRIPTS 

By setting die parent properties of scripts and thus linking them in inheritance 
chains, your program limits unnecessary duplication of script objects. Still, when 
AppleScript sets the parent of a script, it stores a copy of die script’s parent (and of 
die parentis parent, and so on) with the original script. This is the basis of the trick 
that allows SimpliFace to simulate sharing scripts between objects: every script carries 
with it a copy of all the scripts it shares. But this is wasteful — it means that, for 
instance, each button script For a window contains a copy of the window's script, 
when only one copy is necessary. Because your program is directly controlling script 
inheritance chains, you’ll want to block this behavior when it loads and stores scripts. 
You can do it by specifying the kOSAModeDontStoreParent Flag when you call 
OSAStore and recreating the inheritance chain when the scripts are reloaded. 

Listing 1 shows the routine used to set the script property of an object in 
SimpiiFace2. Note how it’s changed from the routine used in SimpliFace: it now 
strips the copied parent scripts from the incoming script so that SimpliFace2 can 
manage the inheritance chain itself. 
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Listing 1 * TScriptabte Object:iSetProperty 


OSErr TScriptableObjecti:SetProperty (DescType propertylD, 

const AEDesc *theData) 


{ 

GSAError err = errAEEventNotHandled; 


switch (propertylD) { 
case pScript: 

OSAID theValuelD = kOSANullScript; 
if (theData->descriptorType = typeChar 

I| theData~>descriptorType == typelntlText) 
err = OSACompilefgScriptingComponent, theData r 

kOSAModeCornpilelntoContext , &theValuelD); 
else { // If it's not text, we assume script is compiled, 

err = OSALoad(gScriptingComponent, theData, kOSAModeNuli, 
stheValuelD); 

// The following new section strips any existing parent script, 
if (err == noErr} { 

AEDesc newData; 

err - OSAStore(gScriptingComponent, theValuelD, 
typeOSAGenericStorage , 
kQSAModeDontStoreFarent, 
kDSAModeDontStoreParent, fcnewData); 
if (err == noErr) { 

OSADispose(gScriptingComponent, theValuelD); 
theValuelD = kOSANullScript; 

err = (OSErr}0SALoad{gScriptingComponent, &newData, 
kOSAModeNuli, fctheValuelD); 
AEDisposeDesc(&newData); 

} 

} 

} 

if (err == noErr) { 

if (fAttachedScript 1= kOSANullScript) 

OSADispose(gScriptingComponent, fAttachedScript); 
fAttachedScript = theValuelD; 
err - SetCurFarent(fFarentObj); 

// This fixes up the references in any object that 
// has the current object as its parent. 
this->FixUpScriptReferences(this); 

} 

break; 

} 

return (OSErr)err; 

} 


ATTACH SHARED HANDLERS AND GLOBAL VARIABLES 
SCRIPTS 

Now die plot thickens. You're going to use the inheritance chain you’ve set up to 
make it possible for your program's AppleScript scripts to share handlers and 
properties and to support global variables. 
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Our strategy, as demonstrated in SimpliFace2 J is to attach a shared handlers script to 
the application object and a global variables script to the global script administrator 
object (which, as in Simp)iFace, is responsible for fetching the script attached to 
objects and preparing it for execution). The shared handlers script, which as a 
convenience for the scripter IVe made a property of the application object (in 
addition to the application object's attached script), defines common subroutines for 
all the object scripts known to the program. This script is added to the end of the 
inheritance chain so that it becomes the parent of all other scripts. Globals are 
created in the global variables script, which is always inserted at the start of the 
AppleScript inheritance chain when an Apple event is handled by a script. 

Let me explain why the global variables script is necessary The AppleScript OSA 
component creates global variables in the script context that received the current 
message, the one at the start of the inheritance chain. If the variables weren't 
predefined as properties when the parent script was defined, they won't be visible to 
all scripts. But we’d like variables that are declared in handlers with the Global 
keyword to be available to handlers In all scripts. We achieve this by adding the global 
variables script that we create to the start of the inheritance chain. Thus, the only 
script actually to be dispatched messages is the global variables script, and its parent 
becomes the currently resolved object's script. Because its parent changes to whatever 
Is the appropriate script in the inheritance chain, messages are handled by die correct 
targets. 

HOW IT ALL WORKS 

The AppleScript-only inheritance approach demonstrated in SirnpKFace2 works like 
this: Whenever the Apple event prehandler receives an event that might be handled 
in a script, it tries to resolve the object that should handle it. If it can't resolve an 
object it assumes that die application object's script should handle the event instead. 

It then attaches the global variables script (the script that receives all incoming 
events) to the start of the inheritance chain that ends w ith the shared handlers script 
(the parent of all scripts). In between is the script of the object to which the event w r as 
targeted; if that object is a button or a field in a window, the inheritance chain also 
contains the window's script. The result is the inheritance chain showm in Figure 5. 



t 

Apple event 
message 


Figure 5. The script inheritance chain used in SimpiiFace2 
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The Apple event prehandler routine in SimpliFace2 calls the global script 
administrator object to manage the scripts, as shown in this extract from the 
prehandler: 

TScriptableObject* theScriptableObj * NULL; 

TScriptableObject* savedParent = NULL; 


if (err == noErr && theToken] 

err = gScriptAdiRinistrator->GetAttachedScript(theToken->GetTokenObj {), 

the Sc ript ab1eOb j, s avedP are nt); 
if (err == noErr) { // Pass to script for handling * 
if [theScriptableObj) 

err = ExecuteEventlnContext(theEvent, theReply, theScriptableObj); 
else 

err = errAEEventNotHandled; 
if (theToken) 

gScriptAdministrator->ReleaseAttached5cript(theToken->GstTGkenQbj(), 

savedParent); 


> 


The script administrator function GetAttaehedScript (Listing 2) is responsible for 
adding the global variables script to the start of the inheritance chain by setting its 
parent to the script of the target object Here’s how it works: First, it asks the 
scriptable object that’s the target for the Apple event message to deliver its attached 
script. If there’s no attached script, the parent of the global variables script is set to be 
the shared handlers script. If the object does have an attached script, that script 
becomes the parent of the global variables script. 


Listing 2, TScripfAdmmlstratonrGefAttachedScnpf 

OSAError TScriptAdministrator:: GetAttaehedScript ( 

TScriptableObject* theObj, 
TScriptableObject* SuseObject, 
TScriptableObject* &savedFarent) 

{ 

OSAError err = noErr; 

OSAID theObjScript = kOSANullScript; 

if (theObj) 

tbeObjScript = theObj->GetObjScript{); 
if (theObjScript 1= kOSANullScript) 

err = StartUsing(theObj, savedParent); 
else // If target has no script, new parent is shared handlers, 
err 3 Startusing(NULL, savedParent); 
if (err J- noErr) 
useObject ® NULL; 
else 

useObject = this; // if OK, return global variables script, 
return err; 
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GetAttaehedScript returns the ID of the global variables script so that the prehandler 
can send the Apple event to the inheritance chain that the script now starts. The 








global variables script receives the Apple event message in the function 
ExecuteEven tin Context, called from the prehandler. The StartUsing function in 
Listing 3, which is inherited bv the script administrator from TScriptableObject, 
returns the current parent of the script so that it can be saved for subsequent 
restoration by the script administrator function Rele as e Attached Script* 


Listing 3. TScriptobleObject::StortUsing 

OSAError TScriptableObject::SetCurParent (TScriptableObject* theParent) 
{ 

OSAError err - noErr; 

OS AID n ewP arentSc riptID * Ge tPa r en t S c ript(); 

if [fAttachedScript 1= kOSANullScript) 

err = gScriptAdministrator->SetScriptParent(gScriptingComponent, 

fAttachedScript, newParentScriptID); 

return err; 


OSAError TScriptableObject::Startusing (TScriptableObject* newParent, 

TScriptableObject* ioldParent) 

{ 

oldParent = fParentObj; // Returned in case it must be saved, 
re tur n S etc u rP are nt{newP arent); 


The parent of the global variables script must be saved and restored every time the 
Apple event prehandler handles an Apple event. This is because Apple events are 
dispatched recursively during the execution of scripts: you should assume that any 
Apple event handler can be interrupting the processing of another Apple event. For 
the same reason, if you need to set the resume/dispatch procedure differently in 
different handlers you must carefully save and restore it each time. The sample code 
in SimpliFaee2 contains examples of how you might do this, 

SimpLiFace2 also shows how you can make global variables persistent, by saving the 
global variables script in a script die in the Preferences folder when the program exits 
and reloading it when the program starts up again. The code to handle this is in the 
script administrator routines Save Global Variables and LoadGlobal Variables, 

A RUN HANDLER WRINKLE 

Be aware of a wrinkle: If yon ever intend to dispatch the Run ('oapp') Apple event to 
an AppleScript inheritance chain, each script in the chain must contain a continue 
run handler. 

on run 

continue run 
end run 

The reason for this is that when AppleScript compiles a script into a script context it 
collects all the top-level statements in the script (those not contained in any handler) 
into a default run handler, so that if die script is simply executed the top-level 
statements will run. If there are no top-level statements, an empty run handler is 
created. The trouble is, this default handler doesn't realize yon want it to continue 
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the Run message, so the message will be caught and lost in che script, never to be 
seen farther along in the inheritance chain. 

INHERITANCE IN OTHER OSA LANGUAGES 

The inheritance scheme just described is specific to AppleScript scripts because it 
relies on OSASetProperty to set up the inheritance chain. This call and others in the 
AppleScript LI API aren’t part of the required OSA API, so not all scripting 
components support them. If your program is to support inheritance in scripts 
written in other OSA languages, it must take control of the message passing between 
scripts in the chain at script execution time. 

Your application can do this by simulating, entirely under program control, the 
mechanism that AppleScript uses. Messages that aren’t handled in a particular script 
in the chain are passed along to the next script in the chain. If they’re continued out 
of, or not handled in, the chain, the program routes them to its standard Apple event 
handlers. The drawback to this approach is that scripting becomes a little more rigid, 
because handlers are resolved only toward the parent rather than wherever they are in 
the chain. The advantage is that it will work with any OSA language that supports the 
event handling API and the Subroutine Apple event, which is the message protocol 
AppleScript uses to call subroutines. 

When your program’s Apple event prehandler deals with an incoming Apple event 
message by passing it to a script, it’s responsible for manually redispatching messages 
that aren’t handled or that are continued along the inheritance chain. The 
SimpliFace2 routine ExecuteEventlnGontext (Listing 4} show's how to do this. The 
first and second parameters to this routine arc the Apple event and reply; the third 
parameter is the scriptable object that is to handle the message. This routine is first 
called from the prehandler, which passes it the scriptable object that starts the 
inheritance chain (the object to which the message was originally sent). The 
scriptable object has a field that’s a reference to its parent object, which can be read 
using the accessor function GetParentObj. If the current object has a parent, the 
routine sets the OSA resume/dispatch procedure to be a recursive call to 
ExecuteEvendnContext, passing the address of the parent object as the reference 
constant. If the current object doesn’t have a parent (if the end of the chain has been 
reached), the routine sets the resume/dispatch procedure to be the program’s 
standard Apple event handler, ignoring the prehandler. 

If the Apple event message isn’t handled in the script of the current object, the routine 
GSADoEvent returns the error errAEEventNotHandied. At this point you must 
manually redispatch the message, mirroring the OS As resume/dispatch mechanism: if 
the current object has a parent, you recursively call ExecuteEven tin Con text, passing 
it the address of the parent object. If you’ve reached the end of the inheritance chain, 
you simply call the program’s standard Apple event handier. 

WHERE YOU'VE BEEN, WHERE YOU'RE GOING 

You’ve learned that implementing inheritance starts with choosing an appropriate 
script inheritance hierarchy With this hierarchy in mind, you can link scripts in an 
inheritance chain, either by setting their parent properties {if you’re working only 
with embedded AppleScript scripts) or by directly controlling inheritance at script 
execution time (if your program needs to support scripts in other OSA languages). 
Then you’re ready to create a shared handlers script and put it at the end of the 
inheritance chain, making it the parent of all scripts, and (if you’re working only with 
AppleScript scripts) Co add a global variables script to the start of the inheritance 
chain where it can receive incoming messages and route them to the correct targets. 
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Listing 4- ExecuteEventlnContext 


static pascal OSErr ExecuteEventlnContext (AppleEvent *theEvent, 

AppleEvent *theReply, 
TSeriptableObject* theSeriptableObj) 

{ 

OSAError err = errAEEventNotHandled; 

OSAID theScriptlD = kQSANullScript; 


> 


if (theSeriptableObj) 

theScriptlD = theSeriptableObj->GetObjScript(); 
else if (gScriptAdministrator) 

theScriptlD = gScripfAdministrator-xSetSharedScript(); 
if (theScriptlD 1= kOSAMullScript) { // Pass to script for handling. 

AEHandlerProcPtr oldReswneProc; 

long oldRefcon; 

TScriptableObject* parentGbj = NULL; 

QSAGetResumeDispatchProc(gScriptingComponent, &oldResumeProc, 

^oldRefcon); 

if (theSeriptableObj) { 

parentQbj = the5criptableGbj->GetParent0bj(); 
err s OSASetResumeDispatchProcfgScriptingComponent, 

(AEHandlerProcPtr) & ExecuteEventlnContext , 

(long)parentQbj); 

} 

else 

err - QSASetResumeDispatchProc(gScriptingComponent, 

kOSAUseStandardDispatch, kOSADontUsePhac); 

if (err — noErr) { 

err = GSABoEvent(gScriptingComponent, theEvent, theScriptlD, 
kOSAModeAlwaysInteract, theReply ); 
if (err » errAEEventNotHandled) ( // Not handled in script, 
if (fheScriptableObj) // Make recursive call. 

err = ExecuteEventlnContext(theEvent, theReply, parentQbj); 
else // Otherwise, dispatch directly to standard handler* 
err = StdAEvtHandler(theEvent, theReply, 0); 

> 

} 

OSASetResumeDispatchProc(gScriptingComponent, oldResumeProc, 

oldRefcon); 


> 

return (OSErr)err; 


You\e seen these techniques illustrated by the sample program SimpliFace2, You can 
simply drop the classes from SimpHFace2 into your own programs, use them as the 
basis ot new programs, or use them as a guide to restructuring existing programs. 
Armed with die information in this article and its predecessor, you should now be 
able to implement an inheritance scheme for scripts in your own software. 


Thanks to our technical reviewers Kevin 
Calhoun, Ron Karr, and jeroen Schalk, and to Lee 
Buck of Software Designs Unlimited,* 
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Q 


What operations cause QuickDraw GX to invalidate its shape caches? We want to 
'maximize drawing performance in our application , and it would he nice to know ahead 
of time when caches will need to he rebuilt. 


A 


As you might imagine, this topic is complex, but we’ll try to explain the basics 
and give you some ideas about improving performance. 


Macintosh 

Q&A 


There are several caches associated with a shape, since each object associated 
with the shape has a separate cache. (By die way, the caches are in the 
QuickDraw GX heap and can be seen using GraphicsBug.) Every time you call 
GXDrawShape, QuickDraw GX determines which caches need to be updated, 
updates them, and then draws the shape. So the first thing to know is that if you 
want GXDrawShape to execute as fast as possible (for instance, if you're 
drawing several shapes and want the time between successive GXDrawShape 
calls to be minimal), you should call GXCaeheShape ahead of time to update 
the shape's caches, minimizing the work GXDrawShape needs to do. 


In general, any time you change information within a shape, you cause 
QuickDraw GX to invalidate at least one of the shape's caches. Layout shapes 
are exceptions to this ru 1 e, however. T lie cache associated with a 1 ayotit shape 
will not be invalidated if all of the following conditions are met: 

* You’re adding characters to the end of the layout shape. 

* There’s a single run ol text within the layout shape. 

* The shape remains on the same device. 

If you’re drawing non-hairline geometric shapes and want to get them on the 
screen as fast as possible, you can set the gxCacheShape attribute of the shape. 
Wi th th is a ttti b u te sc t, Q ui ckD ra w C X will pre p ro cess a II the req u i red pa rts of 
a shape into compressed bitmaps. This means the shape is completely ready to 
be drawn when you call GXDrawShape: the hits are just blasted to the screen. 

Any time you change a view port's clip or mapping, QuickDraw GX will update 
all of the caches for the shapes and child view ports associated with that view 
port. There isn’t any speed advantage to setting the clip or mapping ol a shape 
rather than the clip or mapping ol the shapes view port; the same work has to 
happen in either case. Note, though, that if the view port contains other shapes 
or has child view ports, their caches will be invalidated, too. You should change 
the v\ew port’s mapping to move a shape only when you want all shapes within 
the view r port to move the same amount. 


Q I'm looking into the possibility of writing a QuickDraw GX printer driver that will 
only print to a file , and Fve run into a couple of stumbling blocks I hope you can help 
with . First, is there a way to create a desktop printer from the Chooser without having 
an actual primer attached or selecting a port? Can I get to the Chooser list so that I can 
display some kind of dummy or ghost printer? The second issue has to do with the user 
interface of the Print dialogs/panels- / would like to set the “Destination: File ” radio 
button and disable the “Destination: Printer” one for QuickDraw GX application 
interfaces* 


A 


There should he no problem creating a printer driver that only prints to a file. 
And yes, users will be able to create a desktop printer from such a driver. You 
can access the Chooser list: for an example of this, look at the source code file 
Chooser.c from any ol the QuickDraw^ GX printer driver samples. You can do 
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whatever you want within the Chooser to handle and display lists of available 
printers for the currently selected printer driver. You'll also need to modify the 
'comm 1 resource to make sure that the Chooser does the right thing. You 
should be able to put a “nops” 'comm 1 resource reference into the 'look' 
resource. 

You can disable any item in the Print dialog by overriding the GXJobPrintDialog 
message and, in your override, getting the destination tag for the appropriate 
item and locking it. This will make the item appear disabled in the dialog. 
PrintingMgnh contains all the tags you can lock. You should be sure to set up 
the item to be gxVolatileOutputDriverCategory so that your settings go away if 
die user switches drivers in the pop-up menu; you can simply OR this with 
collectionLoclnVla.sk when you set the item’s attributes. 


Q 


The documentation seems a hit thin on what resource type/ID is needed for ColorSync 
profiles in QuickDraw GX printer drivers. Is the appropriate type prof or 'cmat? 
Will QuickDraw GX automatically use one iff stick it in my driven or do I also have 
to override the various profile messages? 


A 


All you need to do is include a cmat' resource with TD gxColorMatchi ngDatalD 
and specify it in your rdip' resource. However, you should also override 
GXFindFormatProfi 1 e so that inquiring applications can ask you what the 
format’s profile will be. Additionally, you should override the GXImagcPage 
message if you want to provide different profiles on a page-by-page basis. 


Q 


I'm working on QuickDraw GX printer drivers. Can you give me some information on 
what must he done to support Pr General? 


A 


PrGeneral support within your QuickDraw GX printer driver is automatic. The 
printing system will automatically maintain the appropriate information within 
the QuickDraw GX print record. The only exception to this automatic support 
is the SetRsl opcode: it you don’t want QuickDraw GX to use the default 
gxReslType resource when the SetRsl opcode is used, you need to define a 
gxReslType resource of your own that reflects the capabilities of your printer. 


Q 


Out application generates its own custom PostScript ™ code when printing to PostScript 
printers. We 'd like to support QuickDraw GX—style printing and still be able to 
continue generating our own custom PostScript code to send directly to the printer. 
What V the best way to handle this? Vve tried generating empty shapes with custom 
PostScript code attached as a tag (using synonyms), but the LaserWriter QuickDraw 
GX driver emits its own “wrapper” code around our custom PostScript code , which 
could alter the printers graphics state . Are there any other methods to achieve this 
without the possible side effects? 


A 


You’re actually very close to sending PostScript code correctly through the 
QuickDraw GX printing system without the side effects* As you already know, 
after a shape with post' tags has been sent to a PostScript printer, QuickDraw 
GX performs a PostScript restore. There's no way to prevent this from 
happening. However, only shape objects cause this behavior; QuickDraw GX 
will not perform a PostScript restore for any other object besides a shape. 


The fastest and best method for sending PostScript code is to attach the code 
with tags (using synonyms) to only one empty shape. You can attach as many 
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tags as are required. We recommend that the tags contain 12K of PostScript 
data each, for optimal performance. If you Ye sending PostScript code down to 
replace the clip or ink or some other object besides a shape, just attach a 'post 1 
tag to the object your PostScript code describes; in this case a restore will not 
occur. 


Q 


How should / download fonts to a PostScript printer under QuickDraw GX? Pm 
sending a direct stream of custom PostScript code , but I don't expect the driver to be aide 
to deduce which fonts need to be included , I've read about the PostScript control tag that 
can be attached to a shape , and I know the structure for the tag contains font 
information, but the documentation about this tag is sketchy. Can you provide more 
details? 


Related to this question, whafs the best way to cause fonts to be downloaded under the 
current Printing Manager! We're using the “draw a single character off the page in 
the proper font" trick. I understand this practice is frowned on. Is there an approved 
way to do this short of intermixing QuickDraw and PostScript code in PkComments? 


A 


Our thinking has changed regarding the use of the PostScript control tag for 
d o w n 1 oading a fon t. I f you wa n t to down! oad a fo n t wi tfa i n you r P os tS c ri p t 
stream, you should call GXF1 alien Font and pass the font within your post' tag. 
The GX PostScript engine will imflatten the font and download it when it finds 
ii attached to your post 1 tag. 


The method you're using (drawing a character off the page) is completely 
supported under QuickDraw GX. It was the recommended method for a long 
time. However, the current recommendation is to use DrawText and pass in text 
that contains all the glyphs you want to use. The reason this approach is better 
for QuickDraw GX is that only the required information is downloaded, 
thereby saving memory on the printer. 


Q 


Do / need to override the GXFree Buffer message in my QuickDraw GX printer driver 
if l perform a total override of the GXDump Buffer message? If l do need to override 
GXFree Buffet; what do I do with the buffer? Should / dispose of it with Dispose Ptr? 


A The documentation is a little confusing about the purpose of the GXFreeBuffer 
message. GXFreeBuffer is sent to ensure that the indicated buffer has been 
processed and is now available for more data; it doesn’t actually dispose of a 
buffer. The only time you need to override GXFreeBuffer is if you’re doing 
custom I/O (the custoinlO flag is set in your 'tobm' resource). The default 
implementation of GXFreeBuflfer will work correctly for QuickDraw GX's 
default buffering mechanism. 


GXFreeBuffer allows you to start asynchronous I/O in GXDm up Buffer; 
then other buffering routines can he sure that operations on a buffer are 
completed before they reuse the buffer (or dispose of it). If you’re overriding 
GXFreeBuffer, you should just hang out in your override until I/O has 
completed for the buffer passed, and then return. If you’re doing synchronous 
I/O, just return immediately, since all I/O must have completed. 


Q 


When I control the start of a QuickTime movie from within my application , the movie 
controller doesn't get updated properly. Pm calling Start Movie to begin the movie as 
soon as it becomes visible, and Pm updating the movie controller like this: 
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theResult := MCDoAction(tmpMovie.fController, mcActionPlay, §curRate); 


However, this doesn't seem to work . What am 1 doing wrong? 


A 


The MCDoAction call with me Action Play doesn't take a pointer to the data in 
the last parameter; h takes the data itself. But since the prototype specifies type 
(void *), to make the compiler happy it must be cast to a pointer. Many people 
have fallen into this trap. 


The recommended method to start a movie when you’re using die standard 
movie controller component is as follows: 


// Play normal speed forward, taking into account the possibility 
// of a movie with a nonstandard PreferredHate, 

Fixed rate = GetMoviePreferredHate(MyMovie); 

MCDoAction(MyMovieController, mcActionPlay, (void *)rate); 

If you do need to use StartMovie, the correct way to cause the movie controller 
to update is to call MCMo vie Changed. 


Q 


We 're using the Conn mini cat ions Toolbox in our application and have noticed some 
strange behavior. Specifically, when a tool is being used , the tools resource fork is 
placed not at the top of the resource chain, but behind the System and application 
resource forks. As a result, were having trouble with tools that use STR# resources that 
conflict with those in our application. This results in bad conf iguration strings or 
configuration dialogs with the wrong text, l can easily work around this by changing 
the resource IDs in my application, but this doesn't solve the problem m the long run ♦ 
Any advice? 


A 


What yon 1 re seeing is a part of the “pathology” of the CouununicaLions 
Toolbox and its tools. Both do a less than perfect job of looking in the correct 
resource map for string resources. The result is what you're currently seeing: 
application strings end up being placed where tool strings arc expected. 


There are a couple of workarounds. The first you've cited, which is to make 
sure that none of your application’s resource ID numbers conflict with the CTB 
tool’s ID numbers. However, as you also noted, this can be a problem when 
you're using several CTB tools, and may not work if the user happens to select a 
too 1 that has a conflicting ID. 


The better way to work around the problem is to save a reference to the current 
resource file and then set the resource file to the System file. After completing a 
call to CM Choose or CMGetConfig, you can reset the resource file to the one 
you started with. Here's how to do this: 


short oldResFile; 

Point dlogBoxPt? 

Ptr myConfigString; 


/* First save the current resource file* */ 
oldResFile = CurResFile(); 

/* Mow set the resource file to the System file, */ 
UseResFile(O); 

/* Next call CMChoose to configure your connection tool* */ 
myErr = CMChoose(&myConnectionHdl, dlogBoxFt, nil); 
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/* flow call CMGetConfig to get the configuration string from the 
connection tool. */ 

myConfigString = CMGetConfig(myConnectionHdi); 

/* And finally, restore the old resource file, */ 

UseResFile(oldResFile); 


Q 


What is the Human Interface suggestion for removing a digital signature from a 
signed document? 1 see how to add and how to verify , but l can V find any suggestions 
for removing signatures. 


Here’s the relevant paragraph from the AOCE Human Interface Guidelines 
document, which can he found on AppleLink (search die AOCE Talk folder): 


Signatures may also be deleted by users. To accomplish this, die user 
should select the signature by clicking on its icon and choosing Clear 
from the application’s Edit menu. Selecting the signature icon and 
pressing the delete key is a desirable alternative. Note that signatures 
must not be cut, copied, or pasted. 


To actually remove a signature, just remove the 'dsig f resource from the file. 
Note that signed files may have the Finder “locked” bit set. If you remove the 
signature, you should also clear this bit. 


Q 


/ launch my application by dragging files onto its icon. It theft opens the files, performs 
some quick operation, and quits. I can put '****' and fold f resources in FREFs to let 
users drag any file or folder onto the application icon. But when a user drags an AOCE 
catalog (or anything inside the catalog) onto the icon , the Finder won't let the user drop 
it onto my application. What do I need to do to my application to let users drop-launch 
it with AOCE catalogs (or their contents) 11 know iti possible: the “Find in Catalog ” 
application will drop-launch if a user dragged to it from a catalog. 


A 


If you look, you’ll see diat “Find in Catalog” is a Catalogs Extension template. 
It’s not an application program; it actually executes as part of the Finder. 
Unfortunately, you can’t do what you want to with an application. You 
might want to look at the Catalog Service Access Modules chapter in Inside 
Macintosh: AOCE Service Access Modules for more information on the Catalogs 
Extension. 


Q 


When users launch my utility application by double-clicking, I present a Standard File 
dialog that lets them choose a file to operate on. Vd like them to be able to browse 
AOCE catalogs as well as 11FSfiles, but catalogs don't show up in the Standard File 
dialog. I could use another dialog for browsing AOCE catalogs , but why use two 
different inte?faces for the same action (from the user's point of view? that is; the user 
just wants to specify an affect, wherever if may be)? Is there a way to get catalogs to 
show up in the Standard File dialog? Is there any way to browse the file system and the 
AOCE catalog system in the same dialog? If the answer is no, is there an analog to 
Standard File for A OCE catalogs? 


A 


You can’t browse HFS files and AOCE catalogs in the same dialog, since they’re 
two different file systems. To let the user browse the AOCE catalog system, you 
need to use the AOCE Standard Catalog Package Reference routines, which are 
documented in Inside Macintosh: AOCE Application Interfaces. There is a routine 
that’s analogous to StandardGetFile. The AOCE Software Developer’s Kit 
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(available through APDA) includes sample code that shows how to browse 
AOCE catalogs. 


Q 


Vm writing an application that will watch a user-specified folder and operate on files or 
folders that are dropped into it I need to perform operations on every item in the folder 
and its subfolders. When will happen if I begin to walk through a new folder with 
PBGetCatlnfo while the Finder is still copying files into the subfolder structure? Can I 
guarantee that I'll detect all the files? 


A 


There’s no way to find out directly when the Finder is done copying items into 
the folder, but there is a strategy we can recommend. First, though, you should 
know diat the recommended way to determine whether items have been added 
to a folder is to watch its modification date. So how can you know when all the 
hies have arrived? The recommended strategy is to poll the parent folder’s 
modification date every few seconds after you first detect a change, and keep 
polling until you have a reasonably long interval during which there’s no change 
in the date (30 seconds is probably about right). This means, of course, that 
there’s a delay before you act on files dropped into the folder, but as the Print 
Monitor shows us, this delay is probably reasonable to the user. 


One more possible gotcha you should know about; to tell whether it’s safe to 
work with a particular file, it’s not enough just to make sure the file isn’t open; 
you need to check its length. If a file is closed (that is, not busy) hut has no 
length in either its resource or data fork, you caught the Finder at an 
uncomfortable time, after it created the file but before it opened it. So to know 
if you can operate on a file the Finder might be copying, you must determine 
two things: it’s not already open, and it has length in its resource or data fork. 


Q 


Oivr application uses the Icon Utilities interface , and we want to verify that these 
features are present before we use them , We*ve been unable to do this successfully. The 
Macintosh Technical Note “Drawing Icons the System 7 Way ” (QuickDraw IS) doesn't 
say how to do this , but Inside Macintosh: More Macintosh Toolbox recommends using 
Gestalt with the gestalt Icon Utilities selector When we tty this , Gestalt returns an error 
of -) > > / (undefined selector). What are we doing wrong? 


A 


There isn’t a Gestalt selector for the Icon Utilities; Inside Macintosh and the 
header files are wrong. Even if we were to correct that situation tomorrow (or 
in the next system software release), it wouldn’t help, since the Icon Utilities are 
available on systems where the Gestalt selector isn’t. The solution is to use the 
TrapAvailable function to see if the _IconD is patch A-trap is available. You can 
find the source code for TrapAvailable in Inside Macintosh Volume VI on page 
3-8, or Ln Inside Macintosh: Overview on page 180. 


Q 


I have a System 7 application that the user can drag files , disks, or folders to , How can I 
determine from the Apple event information which type of item (file , disk, or folder) has 
been dragged to the application icon? 


When the user drags a file, disk, or folder to an application icon, the Finder 
uses the Process Manager to open the application and then sends it an Open 
Document (' odoc) event containing a list of alias records for each object 
dropped. When your application receives the event, it needs to open each of 
the objects specified in the event by getting each alias record from the list and 
coercing the data for that record to an FSSpcc. Once you have the FSSpec, you 
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can check its parlD to determine whether the directory ID is fsRtParlD, 
indicating that you’re looking at a volume. If the parED is anything other than 
fsRtParlD, use PBGetCatlnfo to determine if you have a file or a folder Here’s 
the code: 

enum {kltsAVolume = 1, kltsAFolder, kltsAFile}? 
pascal GSErr GetSpecType(FSSpec *myFS£) 

{ 

CInfoPBRec pb? 

OSErr myErr; 

short objType = 0 ; 

if ((myFSS~>parID) == fsRtParlD) 
objType = kltsAVolume? 
else { 

pb.hFilelnfoToHamePtr “ (StringPtr) *{myFSS), name; 
pb.hFilelnfo.ioVRefNum = *{myFSS).vRefNum; 
pb.hFileInfo*ioDirID = *(myFSS),parID; 
pb/hFilelnfoToFDirlndex = 0? 
myErr = PBGetCatInfoSync(&pb); 
if (myErr = noErr) { 

/* Check to see if bit 0x10 of ioFlAttrib is set? if it is r 
we've got a directory */ 
if ((pb.hFilelnfo*ioFlAttrib & 0x10) 1= 0) 
objType = kltsAFolder; 
else 

objType = kltsAFile; 

} 

} 

return (objType); 

} 


Pm trying to implement “the perfect component. ” The goals for this component are fast 
dispatchings delegatable, able to rely on delegates, ready for everything, and surprised 
by nothing, Vve been using develop Issues 12 and 14 and inside Macintosh: More 
Macintosh Toolbox to guide me, but / still have a question that wasn't addressed in those 
references ♦ 


Pm using the Fust Dispatch method to dispatch my component's calls. / Te figured out 
how to repair the stack after getting an unsupported routine selector code , but l can V 
figure out how to delegate a call. I think Vm recovering the stack correctly, but all the 
documentation Tve read doesn ¥ even hint at this son of functionality. I was thinking 
that / could use Delegate Compon en tCall after creating a Component Parameter record , 
or I amid calm (ate the size of the parameters and attempt to set up the stack for a 
Compon en t Call Now call. However, neither of these is a good solution — they both take 
too many instructions to implement and obviate the advantages of fast dispatching. Is 
there such a thing as a DelegateFastCotnponeniCall that / haven't heard of? 


A 


Try the following to delegate a component call: 


move.l dO, -(sp) ? push dO onto stack 

PUSHDELEGATEGUY ? macro to push component instance 

move*q #-2,d0 
dc.v $a82a 
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What apparently happened is that the engineers realized how difficult it was to 
call DelegateCornponentCall when the stack was screwed up. So they created a 
“special” delegate call. As you can see, the selector is -2. This is supposed to be 
documented somewhere in the Component Manager documentation, but was 
in a d ve rten tly left out. 


Q 


Why aren't my components getting register calls? Fve set the appropriate flag. In? 
registering the component from my application . 


A 


Your component won't get called to register at all since it's being registered by 
an application. If you removed your component and placed it in the Extensions 
folder so that it was registered at system startup, it would receive a register call. 
The reason for this is that registration of components happens only when the 
Component Manager is first loaded at system startup. After system startup, 
components can be registered by applications, but the register routine will not 
be called. 


Q 


/ heard that the new Apple digital camera will introduce a graphics format called 
Quick lake. Is this truly a new format or are these just QuickTime compressed FICTs? 
If its a new format, where can I find documentation on it? 


A QuickTake stores its pictures as compressed PICT files. There's a new CODEC 
that's necessary to decompress the images, but no new file type. The QuickTake 
100 Digital Camera Developer Note contains extensive information about 
talking to the camera from both Macintosh and Windows machines. It also 
documents the picture formats. The QuickTake Camera Software Development 
Kit is available from APDA. 


The QuickTake application that comes with the camera can save the pictures in 
a variety of formats, including PICT (with or without various compressions) 
and TIFF. There’s also a control panel that allows the user to mount the camera 
as a read-only serial RAM disk (similar to Mountlmage), so your application can 
directly download the information from the camera's memory. 


Q 


Fm writing my first action atom for the Installer l tried writing a skeletal example, as 
follows: 


resource ’inaa' (30000) { 

£ormat2 { 

contimieBusyCursors, actAfter, dontActOnRemove, 
actQnlnstall, 

1 infn 1 , 149, 

Or 

1000 , 

"Delete Folder" 


#i n c1 ude " Ac t ion At omHe ader, h" 


ActionAtomResult Ac tionAtomForniat2 (Action Atom2PBPtr aa) 

{ 

Debugger(); 

return (kActionAtomResultContinue ); 
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But the action never gets called! I don Y have to explicitly refer to the *inaa * anywhere, 
do If I checked that the resources were copied into the file correctly and had the right 
IDs. What am I doing wrong? 


A 


Your action atom is fine. The only mistake youVe made is not tying your inaa' 
to a package (’inpk'). You have to add to your inaa' a reference to an active 
inpk'. Once you do that, it works great. (We had trouble with this one until we 
found a cool diagram on page 8 of the Installer documentation that shows how 
the script resources interrelate; that diagram is your friend, and seems to 
encapsulate quite a bit of critical information.) 


Q 


Were planning a zone name change for the zone that contains some of our PowerShare 
servers. Will this require any action on the pan of the administrators of the various 
servers beyond informing users of the change? 


A 


It depends on whether you Ye changing the zone names of some or all of the 
servers. If you Ye changing the names of only some servers, it J s entirely possible 
that you don’t have to notify anybody depending on how you’ve replicated your 
folders. For a while the new servers won’t be contacted by any clients since all 
clients will try to address them at their old location, hut eventually all servers 
will again start receiving requests from clients. 


If you Ye changing the zone names of all the servers, the client software won’t 
recognize that the zone names have changed, so you’ll have to throw away your 
hey chain and add it again after the zone names have changed. The PowerShare 
servers will eventually recover and rediscover all the other servers. We 
recommend that you bring up the Master Pathfinder first after changing its 
zone name and then bring up all the other servers. Once all the servers are up, it 
should take a few hours at most for everything to settle down again and lor the 
system to be purring. 


Q 


'The function SMPEnumerateBlocks takes a buffer that returns infonnation about the 
blocks in a letter. The documentation (Inside Macintosh: AOCE Application Interfaces, 
page 3-87) says that the buffer contains u a count byte indicating the number of blocks in 
the letter, followed by a block information structure for each block. ” / can V find 
anything that tells me what a “block information structure" is. 


It looks to me as if it actually returns the count of blocks in a short, not a byte. Is this the 
total number of blocks, or the number of blocks returned by the call? If I have to call the 
function again to get information that did?? Y fit in the buffer ,; do I get another count 
followed by more block information structures, or do I just get an array with more block 
information structures without the count (short) ? 


The block information structure seems to be 16 bytes long, starting with an 
OCECreatorType structure. Is this always correct, and what is the other information? 


A 


This is somewhat confusing. The “block information structure” referred to here 
is the MailBlocklnfo structure defined in die OCEMail.h header file: 


struct MailBlocklnfo 
OCECreatorType 
unsigned long 
unsigned long 


i 

blockType; 

offset; 

blockLength; 
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And yes, the count byte returned in the buffer you provide is actually a short 
(the documentation is wrong). This value is placed right in front of the first 
MaiJBlocklnfo structure each time you make the call. The count indicates the 
number of blocks that were put in your buffer for this particular call (not the 
total), which of course depends on the size of the buffer you pass; it fits in as 
many as it can. Check die “more” parameter to see if your buffer was too small 
to hold all the blocks, and check the nextlndex parameter for the sequence 
number of the next item to be returned. 


Q 


l found what I think is a problem with the TEGetOffset routine: when it returns, a 
28-hyte handle has been locked for single-styled text. I believe its a style handle that gets 
locked. This seems to he m intermittent bug , occurring only about half the time. Is there 
a workaround? Is it safe to just unlock the style handle after calling TEGetOffset? 


A 


Ids a bug all right, and it is the style handle that s getting locked. Here’s a 
workaround: 


static short MyTEGetOffset(Point pt, TEHandle th) 

t 

TEStyleHandle sh; 
short theResult; 

char saveState; 

if (th m ol) 
return; 

sh = GetStyleHandle(th); 
saveState = HGetState(sh); 
theResult = TEGetOffset(pt,th); 

HSetState(sh, saveState ); 
return theResult; 


Q 


/ have a question about the Japanese art of bonsai (colloquially known as stunting 
trees): What happens if you bonsai a fruit tree? Does the fruit come out dwarfed as 
well? Or does the tiny tree produce full-size fruit? 


A 


This was a difficult one to find an answer to. It seems to depend on many 
factors, not die least of which is the kind of fruit tree you’re talking about. One 
person we talked to said he once saw a bonsai lemon tree nine inches tall, with a 
single, full-size lemon hanging from a branch. (Actually, die lemon didn’t hang; 
it would have broken the poor tree. Instead it rested on a small platform built 
especially for that purpose,) But there were also reports of a stunted crabapple 
tree that produced apples the size of peas. Go figure. 


These answers are supplied by the 

technical gurus in Apple's Developer Support 
Center. Special thanks to Pete ("Luke"] Alexander, 
Joel Cannon, Mark (The Red") Harlan, Dave 
Hersey, Dave Johnson, Don Johnson, Scott 


Kuechle, Jim Luther, Kevin Mellonder, Jim 
Mensch, Martin Minow, and John Wang for the 
material in this Q & A column. If you need more 
answers, take a look at the Macintosh Q & A 
Technical Notes on this issue's CD. * 
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THE VETERAN 
NEOPHYTE 

Rubber Meets 
Road 


DAVE JOHNSON 


IVe been thinking about edges lately — about the 
places where dissimilar domains meet and interact. You 
know how every now' and then you come up with a new 
view ? on things? A new model to try to fit the facts into, 
a new lens to use to examine the world, a new pattern 
that you haven't noticed before but that suddenly seems 
pervasive? Edges are like that right now for me. It 
seems that everywhere I look I see edges, and the edge 
always seems to be where the action is. 

I think it started in January, when T was called for jury 
duty. I w as promptly selected to serve on a long, 
complex, and sordid criminal trial. IVe been called for 
jury duty only once before, and that time the 
experience was short and dull. I did serve on two juries, 
but neither trial lasted more than a couple of days, and 
they were both very mundane. This time w as decidedly 
different. There were 4 defendants, 53 separate counts 
to decide, 3 different crime scenes, dozens of spent 
bullet casing's and slugs and shotgun waddings to keep 
track of, something like 14 police witnesses and 6 or 8 
civilian witnesses, a two-inch thick stack of 8 by 10 
color glossies, and lots more. The whole adventure 
took nine weeks to play out. Yow. 

The atmosphere in the courtroom spanned the full 
range of intensities. There was plenty of plodding 
boredom: day after somnolent day of slow, thorough, 
painstaking ballistics testimony, matching bullets to 
guns and mapping where they were found. There was 
high drama: the tapes of the police transmissions 
during the chase and as the final shootout began were 
filled with panic, screaming. There was humor: Helen 
in chair 5 often started to fall asleep in the afternoons. 
The court reporter would see her dropping off, make a 
little hissing noise, and Wes in chair 4 vmuld 
surreptitiously nudge Helen back to consciousness. 
We’d all grin. 


But no matter what was happening at the moment, I 
found the process absolutely riveting, from beginning to 
end. Here were the great and mighty wheels of justice 
in America, slowly and ponderously turning, grinding 
away at the facts like so much dry corn under a 
millstone. The courtroom is a place where politics 
actually collides directly with people’s lives, through the 
strange intervening filter called law It’s an edge, an 
active boundary separating two domains, where work 
actually gets done. 

Pm constandy drawn to active boundaries like that, 
places where two dynamic systems collide and affect 
each other. Interfaces. Precipices. Limits. Edges, And 
they are everywhere. In a previous column I pointed 
out an edge in the realm of language: semantics, where 
a language’s structure collides with meaning and where 
the real work of the language — creating meaning from 
abstract symbols — gets done. In biology, there are 
edges all over the place. An obvious and important one 
is the semi-permeable membrane. Ids the structure that 
allows life to create and control its own environment, 
and ids arguably the single most important structure 
enabling complex multicellular life to exist. Biologically 
active molecules are active because of their shape> dieir 
boundaries; proteins and enzymes work because they fit 
together with complementary molecules. In philosophy 
there is the edge between self and not-self, and 
teetering along this edge, hopping back and forth 
across it and trying to look at it from all angles, is how 
the work of philosophy gets done. In physics, often the 
edges are where the truly interesting — and, not 
coincidentally, mathematically intractable — stuff 
happens. (In engineering school, an all-too-common 
phrase was “ignore edge effects.”) 

.All the exciting stuff seems to happen at edges. Large 
systems diat incorporate feedback often exhibit a 
behavior known as “self-organized criticality” in which 
they evolve toward a critical state, an edge, and 
forevermore exist there, teetering on the crumbling lip 
of stability. A great example is a conical pile of sand on 
a circular plate, with grains being added to the top one 
at a time. Over time the overall shape of the pile will 
change very little, but if you turn up the magnification 
and look closely at the side of the pile, there are 
constant avalanches of all sizes, all extremely 
unpredictable and chaotic. 'This is an interesting dual 
behavior: atone scale there is incredible robustness; the 
overall shape of the pile is very stable and will always 
recover itself, even if disturbed. But on a smaller scale, 
the scale of an individual grain on the side of the pile, 
the dynamics are wildly unpredictable and incredibly 


DAVE JOHNSON likes to try to slip new words he's learned into ago he learned the word enantbmorph. As you might imagine, 

casual conversations without anyone really noticing. Two years he's still waiting for the right opening.* 


110 dev slop Issue 19 September 1994 








////stable. The pile is poised at a limit, a dynamic 
balance between growth and decay. 

An interesting thing is how many different varieties of 
dynamic systems seem to exhibit this kind of behavior. 
The locations and magnitudes of earthquakes, 
fluctuations in traffic flow, the rise and fall of economic 
markets, the rhythmic variations in a heartbeat, the 
varying current through a resistor, and the population 
changes in an ecosystem all exhibit dynamic 
characteristics similar to the sand pile, and this is not an 
exhaustive list by any means. That state, pushed up 
against the edge of stability, seems to be a natural one. 
Life itself appears to he delicately poised on the 
boundary between order and chaos. 

In computers (you knew I was going to get around to 
this eventually, didn’t you?), as in any complex system, 
there are lots of interesting edges and boundaries if you 
look for them. Internally, there’s the place where the 
software collides with the hardware; sparks really fly 
down there, all right. Object-oriented programming is 
all about repackaging the boundaries between and 
among data and functions. (A large part of good object 
design is minimizing the “surface area 1 ’ of your objects.) 
And then there’s the edge of the computer itself And I 
don’t mean the plastic or metal surface of the box, but 
the experiential boundary, the true edge between the 
machine and the user, die interface. Here the animal 
collides with the machine, and the boundary between 
them is infinitely convoluted, elastic, dynamic, and 
interesting. 

For software designers, perhaps the most important 
lesson to be learned from the edge-centric view is this: 
the shape of a boundary defines the shape of things on 
both sides of the boundary simultaneously. The 
boundary of my dog Natty defines not only her own 
shape, but that of a Natty-shaped hole in the air as well. 
The edge between two interlocking tiles in an Escher 
drawing defines the shape of both dies at once. If the 
edge in question is one we have control over, this can 
be very important. 

By programming a computer we’re not only shaping 
die machine; we’re also shaping the humans who use it. 


This is often overlooked, but is crucial to designing 
good software; it needs to fit . Humans are incredibly 
adaptable, and will contort themselves grotesquely to 
use aw kward tools, if necessary. Like kids with dieir 
faces squashed against the toy store window, computer 
users smash themselves up against the interface — even 
though it might hurt — to get at what’s inside. 

But because of the chameleon-like nature of the 
computer, we have more or less total control over the 
interface. So in principle we have the power to shape 
die computer to the user, rather than the other way 
around. We should be able to make a truly human¬ 
shaped dent in the computer, a dent people can slip 
into effortlessly and comfortably, like slipping into a 
fuzzy slipper. It’s incredibly hard work, shaping die 
computer to the human, all that snipping and tucking 
and smoothing. It requires constant readjustment, 
painstaking attention to detail, and massive amounts of 
brute-force trial and error. But it’s good work, some 
w'ould say the work that humans are best at: the 
shaping of tools. 

So now' here I am, seeing edges everywhere. Sigh. Last 
year it w'as basins of attraction, this year it’s edges, next 
year maybe it’ll be networks of interconnections. But 
diere’s one thing I can count on: every time I get tired 
of looking through one particular glass, there will he 
another within reach. Humans have diis uncanny 
ability to apply order to everything they see, to perceive 
structure in everything around them. Our minds seem 
to operate by forming and then reforming meaning, 
establishing and then reestablishing context, constantly 
slipping and adjusting to accommodate the relendess 
stream of input. Hmm. Just like that pile of sand. 


RECOMMENDED READING 

* Complexity: The Emerging Science at the Edge of 
Order and Chaos by M, Mitchell Waldrop (Simon 
& Schuster, 1992). 

* How Dogs Really Work! by Alon Snow [Little, 
Brown and Company 1993). 


Thanks to Jeff Barbase, Michael Clark, Michael Greenspan, 
Brian Hamlin, Mark (The Red") Harlan, Bo3b Johnson, Lrso 
Jongewaard, and Ned van Alslyne for their always enlightening 
review comments.* 


Dave welcomes feedback on his musings. He can be reached 
at JOHNSON.DK on AppleLink, dkj@apple.com on the Internet, or 
75300,715 an CompuServe.* 
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Newton 
Q&A: 
Ask the 
Llama 


Q 


Fm having trouble with the protoRoll. I have a protoApp with a protoRoll at the bottom 
with a couple of items in it (Note that Pm not using the protoRoll Browser proto.) It 
compiles OK, but when I download to the Newton, nothing shows up. In fact, when I 
use the inspector to look at the view hierarchy , the protoRoll doesn V show up at all. The 
other views are fine. What am I doing wrong? 


A The protoRoll doesn't show up because of the setting of the viewFlags of the 
ROxM prototype: the vApplication and vClipping flags are set, but not the 
vVisible flag. If the protoRoll were the base template of your application, the 
vApplication flag would be sufficient to make it visible. 


In your case, the protoRoll is a child of your base application template. Since it 
isn’t visible (vVisible isn’t set), the system doesn’t create a runtime view frame 
for the child. You could get the system to create the runtime view by declaring 
the protoRoll to be the base template, but this still wouldn’t show the protoRoll, 

To make die protoRoll visible, add a viewFlags slot to the protoRoll and check 
the vVisible flag. You may or may not want to uncheck the vApplication flag. If 
you uncheck it, the system will no longer send scroll and overview messages 
(viewScrolIUpScript, viewScrollDownScript, viewOverviewScript) to the 
protoRoll, so it will appear to be broken. But you can support these messages in 
your base application view and just pass them on to the protoRoll as needed. If 
you leave the vApplication flag checked, protoRoll will got the scroll events. 


Q 


My print format never seems to get called\ even I don J t get a printNextPageScript or 
even a viewSetupFonnScript Fm not using ROM coverPageFonnat because I don't 
ever want to prim a cover page. How can I get this to work? 


A 


The answer to your problem is in your question, A print (or fax) format must 
proto to RQM_coverPageFonmt; it’s not optional (as the manual implies). It may 
help to know that ROM _coverP age Format is really misnamed. The generation 
of a cover page is controlled by a slot in your format. The proto should be 
called something like ROM_a HThePri ntingAn dFaxin gB eh a vior Proto, but that 
would be verbose :-) 


Q 

A 


/ would like to add a [button I view I Llama] to the [Notepad I Calendar I Cardfile I etc.]. 
How can I do that safely? 

Phis is a simple one: you can’t. If you add any element to a built-in application, 
you take the chance that your application will break in future releases of 
MessagePad, Also note that adding llamas to MessagePad will theoretically 
cause a multidimensional implosion. (“Don't cross the llamas* er , . . beams.” — 
Llama Busters) 


Q 


Vve noticed some peculiar behavior in the Compile function and am wondering if it 
might he a bug , The problem is with special characters and string objects, li ken 
Compile is passed a string object containing special characters rather than a literal 
string with Unicode codes , the result is incorrect. This example works as expected: 


The llama is the unofficial mascot of the NewtonMail DR LLAMA or AppleLink DR. LLAMA. 

Developer Technical Support group in Apple's The first time we use a question from you, well 

Personal Interactive Electronics (PIE) division. send you a T-shirt * 

Send your Newton-related questions to 
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x: = Compile(" {msg: \"A string with special character \uQ0A5\u\" } M ; 

y;= :*{); 

—> y is {msg: "A string with special character ¥”} 

This example doesn V work as expected: 

a: = "A string with special character \uQ0A5\u"; 
x := Compile(a ); 
y;= :xO; 

—> y /.v (msg: U A string with special character *”} where * is some character other than 
the expected ”¥'\ 

Can you explain what s going on here? 

The problem is that you’re using illegal NewtonScript syntax in the second 
example. If you used the inspector instead of Compile for this example, it would 
be like typing 

A string with special character \uOGA5\u 

and then hitting Enter. This would result in a syntax error from NewtonScript. 
What you probably want is the equivalent of typing 

■'A string with special character VuOOA5\u” 


into the inspector. This is done with the following call to Compile: 

x Compile( n \ ,r A string with special character WuOGA5\\u\"") ; 

call x with (); 

—> #4415F49 "A string with special character ¥" 

Note that the escape characters (\) for the Unicode string are themselves 
escaped. If you don’t do this, you’ll be putting the actual Unicode characters 
into the string being compiled, w hich is probably not what you want. /VIthough 
your first example worked, you could easily get a case where not escaping die 
escape characters could bite you. 


In the communications input spec helow, why does the call to UpdateStatus fail? 
UpdateStatus is a method in my base view, and the whole endpoint is in my base view, 
so why can i the input spec find the method? 

GetMessage; { 

inputFonn; 'string, 
endCharacter: unicodeCH, 

InputScript: fune(endpoint, data) 
begin 

:UpdateStatus(data); 
endpoint:SetlnputSpec{GetMessage); 
end; 

1 

The call to UpdateStatus fails because it’s a message send that uses full 
inheritance to find the method. That means the system will look in the current 




context (that is, self)* then check the proto chain, and then check die parent 
chain. However, the current context is not what you think it is. In an input spec, 
the current context is the frame that defines the input spec. In this case, it’s the 
GetMessage frame you define. 

Since the GetMessage frame has no proto or parent pointer, the message send 
fails. There's a second problem waiting to happen: the call to SetlnputSpec will 
also fail, because the symbol GetMessage isn’t valid in this context. 

The solution is to get a reference to your base view (or another view that 
contains or inherits the UpdateStatus message). The usual way to do this is to 
add an _parent slot to your endpoint at run time during initialization. Now r your 
InputScript can use endpoint._parent to find the base view, as follows: 

InputScript: func(endpoint, data) 
begin 

endpoint;UpdateStatus[data); 
endpoint:SetlnputSpec(endpoint.GetMessage); 
end; 

If you really want to use a simple message send (for example, dJpdateStatus), 
you could add an _parem slot to the input spec. "1 'his may be useful in situations 
where you have several input scripts that rely on a dynamic inheritance 
mechanism. That is, you change what the _parem slot of the input spec points 
to on the fly. 


Q 

A 

Q 


Did you know that “gullible* is not in the Newton dictionary? 
It is now. 


/ have a large amount of static data in my application. Vd like to use Project Data to 
edit this data, hut it won V jit. What can I do? 


A 


You must have an old version of the Newton Toolkit, As of version 1.0.1, die 
32K limit is gone. You could use another text editor to edit the Project Data file. 
You could also use the Load command to load another NewtonScript source 
file. 


As an example, assume you had a file called MyData.fin the same directory as 
your project and that this file contained the script that defined your constant 
data structures. You could use the Load command like this: 


// This line appears in your Project Data file. 

// toad in the data file and use the HOME compile-time variable 
//to get the path to the project folder. 

Load{HOME & "MyData.f"); 


Q 


How can ( figure out how much space my package and data will take an a card? I really 
want my application to fit on a 1-meg card. 


A 


The short answer is, you can’t. The long answer is, load your packages and 
soups after completely erasing the card. To completely erase the card, open up 
preferences and then insert the card. Before the card is loaded, you’ll get a 
chance to erase it. 
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Look at the difference in the free space on the card. Use the value in the card 
dialog. The value in the remove-package picker is the uncompressed size. You 
must erase the card before you check the free space difference. 


Q 


/ have an input spec that receives data and places it into a queue. When 1 get data , / set 
a flag in my base view (Datain0) that indicates data is available. 1 know the data is 
getting sent\ but my input specs never seem to get called. What's going on? 


A 


The chances are that your base view has some code like this: 


myBase.WaitForData := func(} 
while Wot DatalnQ do nil; 

You may have more statements in the loop, and you may be using repeat 
instead of while, but you probably have a loop that waits for the DatalnQ 
flag to be set. The problem is that you’re not giving control back to the 
Newton Seri pi thread so that it can process the pending InputScript call (from 
your input spec). 

If you really need to wait for data, you can use either an idle script or a 
repeating delayed action. The idle script will be significantly easier to 
implement. You should make the delay on your idle script long enough to give 
time to the Newton. Also note that the Newton is a battery-powered device, 
and excessive use of this kind of programming tends to drain the users — 1 
mean, batteries. 


Q 


/ have an array of text elements called My latest Array in my Project Data file. I want 
to set the text of a cl Paragraph View that I open to an item in this array. The 
ciParagraphView has a slot (strRef) that references My First A rrayf0 /. The first element 
appears as the cl Paragraph s view. There are four buttons on the base view , and 
depending on which button is tapped 1 want a different element of this array to be the 
cl Paragraph's text. When 1 try replacing MyFirstA rray j Of in str Ref during the 
vicwSctup Form Script, I get as text “MyFirstArray [1 j ”, not the text this represents. 
Here's the code in SetupFormScript in the cl Paragraph: 


SetValue( self , T strRef, "MyFirst Array [ "Si temps lot &" ]"); 


tempslot is a slot in the base view where I store a value depending on which button is 
tapped. What's the problem? 


A 


The basic answer is that your SetValue statement is incorrect. This statement 
sets strRef to the string “MyFirstArray [” concatenated with die string 
representation of tempslot concatenated with What you really want is the 
string that’s in MyFirstArray at the position defined by tempslot; that statement 
would be 


SetValue(self, 1 strRef, MyFirstArrayftempslot]); 

But there are better ways to do this. Which method you use depends on when 
you set the text of the ciParagraphView. If you set up thing's at open time, use 
the viewSetupFormScript, but just assign directly to the text slot: 

ciParagraphView.viewSetupFormScript := func() 
text # — MyFirstArray[tempslot]; 
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Remember that SetValue will also dirty the view and call Refresh Views. This 
isn’t something you want to happen when you Open a view. 

The other case is that the clParagraphView is already open. In this case, you can 
use a SetValue statement to set the text slot directly, instead of setting a strRef 
slot. 

One other note: If the user can edit the strings you place in a clParagraphView, 
you must Clone the string. Otherwise you can get a “tried to modify read only 
object” error. 


Q 

A 


How long does it take to train a llama to he a competent NewtonScript programmer? 
About four weeks, but the hooves get in the way of really fast coding. 


Thanks to our PIE Partners for the questions Have more questions? Need more answers? 

used In this column, and to jXopher, Todd Take a look at PIE Developer Info on AppleLink.* 

Courtois, Bob Ebert, Mike Engber, Kent Sandvik, 

Jim Schram, Maurice Sharp, and Scott ("Zz' f ) 

Zimmerman for the answers. * 


Do you yearn for the adulation of your colleagues? 



Yearn no more; w r rite for develop. We’re alw ays looking lor people 
who might be interested in submitting an article or a column. If 
you’d like to spotlight and distribute your code to thousands of 
developers of Apple products, here’s your opportunity. 

If you’re a lot better at writing code than writing articles, don’t 
worry An editor will w r ork with you. The result will be something 
you’ll be proud to show r your colleagues (and your Mom). 

So don’t just sit on those great ideas; feel the thrill of seeing them 
published in develop 1 . 


For Author’s Guidelines, editorial schedule, and information 
on our incentive program, send a message to DEVELOP on 
AppleLink, deveIop@applelink.apple.com on the Internet, or 
Caroline Rose, Apple Computer, Inc., One Infinite Loop, 
M/S 3G3-4DP, Cupertino, CA 95014. 
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KON & BAL'S PUZZLE PAGE 


Heaps of Fun 



KONSTANTIN OTHMER, 
BRUCE LEAK, 

AND STEVE NEWMAN 


See if you can solve this programming puzzle , presented in the form of 
a dialog between Konstantin Othmer (KON) and Bruce Leak (BAL) 
— and a special guest , developer Steve Newman. The dialog gives clues 
to help you. Keep guessing until you 're done; your score is the number to 
the left of the clue that gave you the correct answer. Even if you never 
run into the particular problems being solved here , you'll learn some 
valuable debugging techniques that will help you solve your own 
programming conundrums. And you'll also learn interesting Macintosh 
trivia. 


Steve I’ve got a machine that crashed into MacsBug, I think it’s this bug that 
some of our beta testers have been reporting; ids really intermittent, so 
I may not get it to happen again. I ! ve got to find it just by looking at 
this one crash. 

KON It’s not reproducible? 

Steve Not if it's the bug I’ve been hearing about. The reports are always the 
same: The machine crashes while saving a file. Afterward the file is 
unreadable. If they go back to an older copy of the file, the problem 
doesn’t recur. No single user seems to have had this crash happen 
more than twice, and no one has been able to associate it with 
something they were doing in the program before they told it to save. 

BAL What does this program do? 



Steve ft’s a PIM — personal information manager Data entry and dialog 

boxes and stuff. It’s a pretty big program, but very vanilla in its use of 
the ROM — striedy Volume I stuff, plus the Memory Manager and 
Fi 1 e Ma n a ge r, o f co u rs e. 

KON You’ve tried stress testing? Heap scramble, low-memory conditions, 
MemHell, QC, all of that? 


KONSTANTIN OTHMER AND BRUCE LEAK 

have given up sleep because they need all Hie 
time they can get to manipulate the penny stock 
market via the budding information superhighway. 
They're no longer trying to break the sound 
barrier but are working on the Hedgehog 
barrier. BAL wonders, "What's that blue 
Hedgehog got that our green Armadillo doesn't 
have?"* 


STEVE NEWMAN (AppleLink STEVENEWMAN) 
has been programming on the Macintosh since 
I 984. Currently, he works at Common Knowledge, 
Inc., writing information management tools. In a 
previous life he cowrote FullPaint, Full Write 
Professional, and Spectre. When asked if he 
thought the Power Macintosh was the hottest new 
game platform he'd seen since the Atari 800, he 
replied "yes/'* 
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Steve 


BAL 


100 Steve 


KON 
95 Steve 
BAL 


90 Steve 
KON 
85 Steve 


BAL 


80 Steve 
KON 


Steve 


BAL 


75 Steve 


BAL 


KON 
70 Steve 


KON 


Yeah. It was a war zone, and we couldn't bring out the bug. But it just 
happened to one of our tech support people, Stephanie* Fve taken over 
her machine until I can figure out what's going on. She closed a file* it 
asked her if she wanted to save changes, she clicked Yes, and it crashed 
i n to Macs B u g w i th an ille gal ins tmcti on. 

Illegal instruction? Sounds like you've branched off into the middle of 
nowhere* Where's the program counter? 

wh pc says we’re in CODE segment 44, $017C bytes into a routine 
called Preflush, According to a link map 1 can look at on another 
machine, segment 44 has the file-saving code. 

Is die heap trashed? 

MacsBug says the heap is fine. 

Perhaps some random memory-trashing bug has overwritten part of 
the code segment. Disassemble around the program counter* 

It looks like valid code, but the PC is in the middle of an instruction. 

Do you have any purgeable code segments? 

We have a fairly complicated code segment management scheme based 
on reference counting* We're pretty careful about it, though; it's been 
a long time since we’ve had any problems there. As it happens, 
segment 44 is purgeable, but it has too many entry points to do 
reference counting, so we just unload it from our event loop. 

Sounds like code right out of the Finder* Let's try to find out how we 
managed to branch into the middle of an instruction. Do a stack crawl 
and see where we came from. Let's look at all die registers to see if one 
of them contains a clue as to how we got here. 

OK. sc6 says the last call came from a function named “Document:: 
SaveAs(int, unsigned char)”. 

What kind of a function name is that? It looks more like a UNIX 
pathname than a function name* 

Hey, you should see what it looks like with name unmangling 
disabled, sc7 shows another return address under that one, in 
“Document::SaveAs(char*, short, unsigned char, int, unsigned char)”* 

SaveAs? 1 thought it was just doing a regular save* And why two 
functions called SaveAs? 

Stephanie insists that it was a regular save — the document had been 
opened from an existing hie and was being saved to that same file. 

But if that were true, the program should have called a function 
named Save, not SaveAs. As far as having two functions with the same 
name, the five-parameter one saves into a specified disk file; the two- 
pa rameter one brings up a Standard File dialog and then ca11 s the five- 
parametcr one. I’m using C++ function overloading. 

You sure you're not running the Finder? Mercer should be able to 
solve this for you in a snap. 

I heard Mercer moved to Chicago. So, how did we get called? 

The call came from a “JSR (Al)" instruction* It looks like a standard 
C++ virtual function call. 

What's the value of Al ? 
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Steve 

It points into the jump table* Disassembling at that address shows a 

JMP to the current program counter. 

KON 

Thar makes sense. Virtual function rabies are stored in the global data 
segment, so their function pointers are data-to-code references, which 
have to go through the jump table. So all virtual function calls go 
through the jump table. That would be necessary no matter how the 
vtables were implemented, since at link time there's no way of knowing 
what version of the function will get called or what segment it's in. 

BAL 

So the jump table is trashed relative to the data in the heap. I still think 
something’s wrong with the heap, MacsBug can be funny about 
deciding whether a heap is trashed. Do a heap dump and page down 
until you see t he hiocIc con ta i n ing the progra m counter. 

65 Steve 

It's code segment 44, and everything around it looks reasonable. But 
there’s a question mark next to the master pointer address. 

KON 

4'hat probably means the master pointer doesn’t point back to this 
heap block. Let’s look at the header for the heap block and find its 
master pointer to double-check MacsBug* The format of the header 
depends on whether the machine is using 24- or 32-bit addressing. We 
can tell the current mode, which is probably the machine’s standard 
mode unless we’re in some slimy QuickDraw code, by looking at 

MacBug’s status display along die left side of the screen. 

Steve 

MacsBug says the machine is in 24-bit mode. It’s an old TIci with only 

8 meg of memory. 

BAL 

In that case, die block header is 8 bytes long. The first byte is a tag 
byte that indicates the type of block (free, pointer, or handle) and the 
slop factor; die next three bytes are the size; and for handles, the final 
four bytes are die offset from the beginning of the heap zone to the 
master pointer for this block. Check that offset in the heap and make 
sure there's a valid master pointer there. 

60 Steve 

It agrees with the location printed in the heap dump* But the value in 
that master pointer doesn’t point back to this heap block. It turns out 

MacsBug won't flag this as heap corruption, but it will put a question 
mark next to the master pointer for blocks where the master pointer 
doesn’t make sense* 

ICON 

Do a heap dump and keep paging down until you find the address that 
it does point to* 

55 Steve 

It points to a block labeled “CODE segment 44”. There are two code 
segment 44s in the heap! 

ICON 

Is there a question mark on this one? 

50 Steve 

No, MacsBug seems to be happy with the second block. According to 

MacsBug, it has the same master pointer address as the first block. 

Both blocks are marked as being locked and purgeable. 

BAL 

But the master pointer really does point to this block, so there's no 
question mark* And “locked and purgeable” is the expected state for a 
purgeable code segment that’s currently loaded — the lock flag 
overrides the purgeable flag. 

KON 

To decide whether a heap block is a resource, MacsBug looks at the 
resource Bag for the block. In a 24-bit heap, that flag is stored in the 
high byte of the master pointer* Since both blocks think they have the 
same master pointer, they’re sharing the same flag byte; anti when 
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Macs Bug searches the open resource maps to figure out which 
resource each block comes from, it gets the same answer 

BAL Now we have two mysteries: why there are two heap blocks with the 
same master pointer, and why the jump table points into the middle of 
a routine. Let’s see if the heap blocks are really the same. Check the 
heap dump to see if they have the same size, and then dump memory 
from each one to see if they’re the same, 

45 Steve They are the same. And by the way, you left out one mystery: If we’re 
doing a Save, why is Save As on die stack? There’s no way that the two- 
parameter Save As can call the five-parameter SaveAs without first 
bringing up the Standard File dialog; but Stephanie insists there was 
no such dialog. 


KON Maybe we took another bad branch through the jump table earlier on. 
Take another look at the stack crawk When did we first enter segment 
44? 


40 Steve A routine called OKToClose, which is not in segment 44, called the 
two-parameter SaveAs, which is. 


BAL Look at the JSR instruction in OKToClose, 


35 Steve It’s jumping to an A5-relative address, in the jump table. That address 
con tains a J MPin to the i niddle of the two-pa ra 11 i e ter SaveAs, shor ti y 
before die place where it calls the five-parameter version. 


KON Aha! By taking a wild branch into the middle of the routine, if skipped 
over the call in Standard File. Maybe all the jump table entries for this 
segment are skewed by the same amount. Disassemble from $017C 
bytes above where this JMP points, 

30 Steve $017C bytes above the JMP target is the beginning of 
Document:: Save. 


BAL That makes sense. OKToClose tried to call into segment 44 to the 

Save routine, but something went wrong with LoadSeg, and it ended 
up $017C bytes tardier down, in the middle of the two-parameter 
SaveAs. Two-parameter SaveAs called five-parameter SaveAs; diis is an 
intra-segment call, so it wasn’t affected by the bad jump table. Then 
five-parameter SaveAs called Preflush, which is a virtual function, so it 
went through the jump table even though it’s in the same segment. 
This time die wild branch happened to hit an illegal instruction, so it 
dropped into Macs Bug. 

KON It’s interesting that the two SaveAs routines were able to function 
more or less correctly even though OKToClose branched into die 
middle of the first routine, thus bypassing all of its parameter setup. 

BAL Well, it sounds like all of these functions are methods of the same 

object. MPW’s C++ compiler usually puts the object pointer in A4. So 
any references to object data members or virtual functions would work 
even though we skipped the entry code for the first SaveAs, 

KON Aren’t all C++ functions fairly interchangeable? Link, save A4, load A4 ? 
test a bit off A4, restore A4, unlink, rts? That’s part of the efficiency. 

BAL In any case, we need to find out what went wrong in the LoadSeg call. 
Maybe there’s a clue on the stack. Dump memory for a few hundred 
bytes starting at the stack pointer. 


develop Issue 19 


September 1994 


120 





25 Steve $0028 bytes after the stack pointer, you notice a funny value: 
S4080BDOA. 

KON That's an address in ROM, probably a return address* Disassemble 
around that address* 

20 Steve It's in LoadSeg, one instruction after a call to StripAddress* It looks 
like this: 


Disassembling from 4080bce0 


_LoadSeg 

+0000 

4080BCE0 

MOVEM.L 

D0-D2/A0/A1,-(A7) 

+0004 

4080BCE4 

MQVE.L 

D1,-{A7} 

+0006 

4080BCE6 

JSR 

Dispatcher+00C6 

+000A 

4080BCEA 

MOVE *1 

(A7]+,D1 

+00 OC 

4080BCEC 

MOVE.W 

$0018(A7),DO 

+0010 

4080BCF0 

BSR * S 

LoadSeg+007C 

+0012 

4080BCF2 

BEQ.S 

LoadSeg+0076 

+0014 

4080BCF4 

HGetState 


+0016 

4080BCF6 

BTST 

#$07,DO 

+ 001A 

4080BCFA 

BNE.S 

LoadSeg+0026 

+001C 

4Q80BCFC 

TST.B 

SegHiEnable 

+0020 

4Q80BD00 

BEQ.S 

LoadSeg+0024 

+0022 

4080BD02 

MoveHHi 


+0024 

4080BD04 

HLock 


+0026 

4080BD06 

MOVE.L 

(A0)iDO 

+0028 

4080BD08 

StripAddress 

+002A 

4080BD0A 

MOVEA.L 

DO,A0 

+ 002C 

4080BD0C 

MOVEA.L 

A5,A1 

+ 002E 

4080BD0E 

ADDA.W 

CurJTOf f set,A1 

+ 0032 

4080BD12 

ADDA.W 

(A0),A1 

+0034 

4080BD14 

CMPI.W 

#$4EF9,$00Q2(A1) 

+00 3A 

4080BD1A 

BEQ.S 

LoadSeg+005C 

+003C 

4080BD1C 

MOVE.W 

$0002(A0),DO 

+0040 

4080BD20 

BEQ.S 

LoadSeg+0Q5C 

+0042 

4080BD22 

MOVE.W 

$001B(A7),D1 

+0046 

4080BD26 

MOVEQ 

#$00,D2 

+0048 

4080BD28 

MOVE *W 

(A1)+,D2 

+004A 

4080BD2A 

MOVE.W 

Dl,-$0002(Al) 

+0G4E 

4080BD2E 

MGVE.W 

#$4EF9,(Al)+ 

+ 0052 

4080BD32 

PEA 

$04(A0,D2.L) 

+0056 

4080BD36 

MOVE .L 

(A7)+,(A1)+ 

+0058 

4080BD38 

SUBQ.W 

#$1,D0 

+005A 

4080BD3A 

BNE.S 

LoadSeg+0048 

+005C 

4080BD3C 

MOVEA.L 

$0014(A7),A1 

+0060 

4080BD40 

SUBQ.L 

#$6,A1 

+0062 

4080BD42 

MOVE.L 

Al,$0016(A7) 

+0066 

4080BD46 

MOVEM.L 

(A7)+,D0-D2/A0/A1 

+006A 

4080BD4A 

ADDQ.W 

#$2,A7 

+00 6C 

4080BD4C 

TST.B 

LoadTrap 

+0070 

4080BD50 

BEQ.S 

LoadSeg+0074 

+0072 

4080BD52 

Debugger 


+0074 

4080BD54 

RTS 


+0076 

4080BD56 

MOVEQ # 

$0F,D0 

+0078 

4080BD58 

SysError 


+00 7A 

4080BD5A 

Debugger 


+007C 

4080BD5C 

ST 

ResLoad 
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+0080 

40808D60 

SUBQ.W 

#$4,A7 

+0082 

4080BD62 

MOVE.L 

#$434F4445,-(A7) 

+0088 

4080BD68 

MOVE.W 

DO,-(A7) 

+008A 

4080BD6A 

GetResource 

+008C 

4080BD6C 

MOVEA.L 

(A7)+,A0 

+008E 

4080BD6E 

MOVE.L 

A0, DO 

+0090 

4080BD70 

RTS 



BAL The JSR to Dispatcher+00C6 flushes the instruction cache. Because 

the 68030 has separate instruction and data caches, LoadSeg needs to 
do that to make sure that the newly loaded data is eligible to make it 
into the cache. Next the subroutine at +007C gets the code resource. 

If the handle isn’t locked, it’s moved high and locked. Then we find the 
first jump table entry for the segment, and test to see if it's loaded by 
checking whether the first instruction is S4EF9 (a JMP.L). If it’s not 
loaded, each entry for this segment is updated from the unloaded form 
(involving a call to LoadSeg) to the loaded form (involving aJMRL). 
But it must have skipped this, because otherwise the PEA at +0052 
would have overwritten the return address from the call to StripAddress, 
and that return address is still on the stack. 


KON It skipped over the code to transform the jump table entries, so the 
segment must have already been loaded. But if the segment was 
loaded, the jump table wouldn’t have any LoadSeg calls for that 
segment. Somehow LoadSeg was called for a segment that was already 
loaded. So your application must be calling LoadSeg manually! 

15 Steve Honest, Fm not calling LoadSeg manually A search of my source code 
verifies this. 


BAL The only other way tor LoadSeg to get called is through the jump 

table. How does your reference-counting segment unloader work? Is it 
possible that a segment gets called by your reference-counting code 
while you’re in the process of loading it? 

10 Steve It shouldn’t be. The reference counting is done manually; we don’t 
patch LoadSeg or anything nasty like that. At any rate, segment 44 
i sn ’t re fe r ei l ce - co li n red. 


KON Here’s an idea: When LoadSeg w as called to bring in segment 44, it 
called GetResource to bring the resource into memory. Assuming the 
code segment had been loaded in the past and later unloaded and 
purged, GetResource would have called ReallocHandle, which was 
short on memory and called your GrowZone hook. Your GrowZone 
function started freeing memory and then called another function in 
segment 44, triggering a recursive call to LoadSeg, 

BAL With enough memory free, segment 44 was loaded. Then the 

GrowZone function exited back to the ReallocHandle call, which 
succeeded, and segment 44 was loaded again when the GetResource 
call completed. When the original LoadSeg checked die state of the 
jump table, it was already kosher, so the test for $4EF9 fired and the 
return address from StripAddress didn’t get overwritten. 

KON That certainly explains the confused heap. The GZSaveHnd that was 
passed to the GrowZone function shouldn’t be touched, but you called 
GetResource on it indirectly via LoadSeg. It also explains the skewed 
jump table entries: after allocating a memory block, ReallocHandle 
simply assigns the master pointer to point to diat block, without 
preserving the handle state stored in the high byte of the master 
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pointer. This effectively sets the handle state to 0, erasing the HLock 
call from the inner LoadSeg, Thus, when the outer LoadSeg called 
MoveHHi on the second copy of the segment, the lock bit in the 
master pointer — which is shared by both blocks — was clear. So when 
MoveHHi called CompactMem, the first copy of the segment was free 
to move (in this case, by $017C bytes). Finally, GetResource returned 
to the original LoadSeg, which set the lock bit again. 

BAL Take another look at your link map. Are there any routines in segment 
44 that could be called from your GrowZone hook? 

5 Steve 'Fhat’s funny. There are some routines in this segment that shouldn’t 
he there — in fact, they shouldn’t be anywhere. They're supposed to 
be inline functions! 


BAL The C++ compiler w r on’t always copy a function inline, even if it’s 
declared that way. This can happen if the function body is too 
complicated. Segment loading is a foreign concept that doesn’t fit well 
into a C++ class hierarchy, and the MPW implementation has a few 
puzzlers. 

KON Some of the calls to these “inline” functions were from segment 44, so 
they happened to be placed in that segment Then, when the 
GrowZone hook tried to call one of the inline functions, it had to load 
segment 44 — and the rest is history. 

BAL C++ claims another victim. 

Steve So how do I avoid this in the future? Put segment #pragmas around all 
my inline functions? 

BAL That’s a superstition believed by some people who should know better. 
It doesn’t work. 


KON What does w r ork is what those Finder folks did. MPW CFront puts the 
uninlineahle functions at the end of the file it’s compiling, 'The Finder 
folks just end every file with “#pragma segment CFrontCruff,” and all 
the unexpected functions wind up in one easy-to-manage segment. 

Steve “Uninlineahle” isn’t a word. 

BAL That’s why it’s called cruft. Incidentally, this technique also catches 
functions that the compiler has to synthesize entirely, such as 
constructors and destructors for classes where they’re needed (to 
initialize the vtable, for example) but aren’t declared explicitly. And by 
looking at the link map, you can see what the compiler is doing behind 
your back — although you might be happier not knowing. 

KON Nasty. 

BAL Yeah. 


SCORING 

80-100 You should be a guest puzzler yourself; send in a draft to AppleLink DEVELOP. 
55-75 Pretty sharp; maybe you can write the first hot OpenDoc container app. 
30-50 Maybe you can write an Open Doc part 
5-25 Moybe you'd better stick to AppleScript* 


Thanks to scoft douglass for reviewing this column, and to Ludis Longens for wading into a haystack 
of hex and emerging with a needle labeled 4080BD0A. * 


KON & BAL'S PUZZLE PAGE 


123 





INDEX 


For a cumulative index to all issues of 
develop, see this issue's CD.* 

A 

active shape (OpenDoc) 11 
“Adding QuickDraw GX Printing 
to QuickDraw Applications” 
(Hersey) 24-47 

AdjustMenus method (OpenDoc) 
15 

AgemBuilder, script inheritance 
and 90 

Alexander, Pete (“Luke”) 65 
AOCE catalogs, browsing 
104-105 

AppIsColorSyncAware (Color 
Picker Manager) 71 
Apple digital camera, Macintosh 
Q&A 107 

AppleScript 1.1 API, script 
inheritance and 89, 91-99 
application-domain objects, script 
inheritance and 91 
application overrides (QuickDraw 
GX) 28-29 

application-owned dialogs, Color 
Picker Manager and 72, 75, 81 
arbitrator object (OpenDoc) 8 
Avitzur, Ron 20 

B 

"Balance of Power” (Evans), 

tuning PowerPC memory usage 
17-19 

bitmapped graphics, QuickDraw 
GX and 48-64 
block headers, KON & B AL 
puzzle 119 

blocking, PowerPC memory usage 
and 18 

bookkeeping calls, OpenDoc 7 
“Building an OpenDoc Part 
Handler” (Piersol) 6-16 

c 

cache lines, PowerPC and 17, 22 
caches, PowerPC memory 7 usage 
and 17-18,22 

cache thrashing, PowerPC and 
17 - 18 , 22 

camera library (QuickDraw GX) 

63 


CanAnimatePalette (Color Picker 
Manager) 71 

CanModifyPalette (Color Picker 
Manager) 70 
canvases (OpenDoc) 1 1 
Catalogs Extension, Macintosh 
Q&A 104 

CClockFramenFrameShape- 
Changed (OpenDoc) 1 1 
C CloekF rame:: In i tC 1 ockF ram e 
(OpenDoc) 12 

CClockPart (OpenDoc) 10, 11, 

12 

C C lo ckP a rt:: D o Ad j us tM enus 
(OpenDoc) 15 

CC1 ockPa rt:: Exte m a l i zeC on tent 
(OpenDoc) 14 

CC1 ockPa rt::Initiallze (OpenDoc) 
12, 13 

CClockPar t;: I n tern al i zeConten t 
(OpenDoc) 14 

CDrawInitiator (OpenDoc) 10 
CFacet class (OpenDoc) 8, 9 
CFacet;;! landieMouseDown 
(OpenDoc) 12 
C Frame: : Acti vate Pram e 
(OpenDoc) 12 

CFrame class (OpenDoc) 8, 9 
CF ram e:: F oeu sSta tc Cha nge d 
(OpenDoc) 12 
CFrontCru ft, KON & BAL 
puzzle 123 

C h eckAn dAdd P r op er t i es 
(OpenDoc) 10 

C h eckl fP i ckc r C an Cl os e (C ol or 
Picker Manager) 80 
cl Para graph View, Newton Q & A 
115-116 

'cmat 1 resource, Macintosh Q & A 
101 

collection index (QuickDraw GX) 
27 

Collection Manager (QuickDraw 7 
GX) 27-28, 38 
collections (QuickDraw GX) 
27-28 

col or-changed procedure (Color 
P i cker M a n age r) 71-73 
Color Picker 2.0 68-84 
color picker dialogs 72-76 
Color Picker Manager 68-84 
setting original/new colors 
76-77 


color picker-owned dialogs, Color 
Picker Manager and 72, 76,81 
colorProc (Color Picker Manager) 
71 

ColorSvnc 

Color Picker 2.0 and 69, 70, 
76, 77 

Macintosh Q&A 101 
Communications Toolbox, 
Macintosh Q&A 103-104 
CompactMem, KON & BAL 
puzzle 123 

Compile function, Newton Q&A 
112-113 

Component Manager 

color pickers and 68 
sequence grabber and 86 
compound documents 6 
constructors (OpenDoc) 9-10 
CopyBits, in QuickDraw GX 
60-61 

CPart:: Ad j ustMenus (Op en D oc) 
15 

CPart class (OpenDoc) 8, 9 
C Pa rt: :D raw (OpenDoc) 10 
CPart: :InitPart (OpenDoc) 10 
C Pa rt; :I nstall M enus (O pe nDoc) 

12 

Cr e a teln d exed B i tma p Shape, 
QuickDraw' GX and 61 
CreateOffsereen, QuickDraw GX 
and 61 

Custom Page Setup command, 
QuickDraw GX and 34-35 
Custom Page Setup dialog, 
QuickDraw GX and 36 

D 

DatalnQ, Newton Q&A 115 
DelegateCom ponentCall, 
Macintosh Q & A 106-1 07 
“Designing Applications for the 
Power Macintosh” (Robbins 
and Avitzur) 20-23 
DialoglsModal (Color Picker 
Manager) 74 

DialoglsMoveahle (Color Picker 
Manager) 74 

dialogOrigin (Color Picker 
Manager) 71 

DialogSelect (Color Picker 
Manager) 78 


124 Jevel Q p Issue 19 September 1994 






direct manipulation, on the Power 
Macintosh 21 
disk- ba s ed bi tma p s ha p es 
(QuickDraw GX) 51-53 
d i s patchero!) j ec t (O pe n D oc) 3 
DoPickerEdit (Color Picker 
Manager) 78, 81-82 
DoPickerEvent (Color Picker 
Manager) 77-80 
D ra w meth () d (O p e n D oc) 10 
DrawText, Macintosh Q & A 102 

E 

Ed it menu, C o i or Pi eke r M a n a ge r 
and 78, 81-82 
escape characters (\), Newton 
Q & A 113 
Evans, Dave 17 
event 111 ter procedure (Color 
Picker Manager) 71-73 
eventProc (Color Picker Manager) 
71 

Exe c Li te Ev cn tl n Context 
(SimpliFace2), script 
inheritance and 97, 98, 99 
ExtractPickerHelpItem (Color 
Picker Manager) 83-84 

F 

Face Span, script inheritance and 
90 

FacetAdded method (Open Doc) 

15 

facet oh j e cts, Op enDoe a nd 8 
FacetRemoved method 
(OpenDoc) 15 
facets (OpenDoc) 9, 15 
Fast Dispatch method 
(com pon ents), Mac i n tos h 
Q& A 106 

flags field (Color Picker Manager) 
70-71 

foci (OpenDoc) 12, 15-16 
Focus method (OpenDoc) 14 
forecast events, Color Picker 
Manager and 80 
format collections (QuickDraw 
GX) 28 

frame objects, OpenDoc and 8 
frames (OpenDoc) 9 f 1 1 
frame shape (OpenDoc) 1 1 

G 

Games folder 3 


Get Attach ed Script, sc r i p t 
inheritance and 96 
( j etC ol or (Col or P i eker Man ager) 
69, 70 

GetMessage, Newton Q & A 

113-114 

GetParentObj, script inheritance 
and 98 

Ge tP i ekerEd 1 tMe n u S ta te (Co I o r 
Picker Manager) 78,81-82 
GetPickerProfile (Color Picker 
Manager) 77 

GetRxMapShape, QuickDraw GX 
and 65 

Get Resource, KON & BAL 
puzzle 1 22 

global variables, script inheritance 
and 94-98 

“Graphical Truffles” (Alexander), a 
cool QuickDraw GX clipping 
effect 65-67 
Graphing Calculator desk 
accessory 20-23 
Grow Zone, KON & BAL puzzle 
122-123 

GXCach e Shape, Ma cin tt >s h 
Q & A 100 

GXChangedShape 51 r 53 
GXCheckBitmapColor 59 
GXConvertPrintRecord 34 
GXCopyDeepToShape 63 
GXCopyToShape 63 
GXDisposeFormat 38 
GXDrawShape 59, 60-61,67 
Macintosh Q & A 100 
GXEnterGraphics 30 
GXEqnalShape 64 
GXFindFormatProhlc, Macintosh 
Q & A 100 
GXFinishPage 42 
GXFlattenFont, Macintosh Q & A 
102 

GXFlattenJob 33 
GXFlattenJobToHdl 33 
GXFormatDialog 36 
GX Free Buffer, Macintosh Q 6c A 
102 

GXGetBirmap 49 
GXGetBitmapParts 64 
GXGetPixelShape 64 
GXG e t S h a pe S tmctur e 51 
GXImagePage, Macintosh Q Sc A 
100 " 

GXlnitPrinting 30 
G XI ns ta 11 Ap p lica ti on O ve r r i d e 28, 
32 


CiXInstallQD Translator 40 
GXj obDefaultFo r matD ialog 36 
gxj o b o'b j eels (Q u i c k D r a w GX) 
creating/disposing of 31-3 2 
saving/loading 33-34 
updating 32-33 
GXJobPrintDialog 36 

Macintosh Q & A 101 
GXLockShape 51,53 
gxM a p 1 r a n s fo rm S h a p e 
(QuickDraw GX) 55 
GXMoveShape 67 
GXNewGra phi cs C lient 30 
GXNewJob 31 

gx PortAI i gn Pa ttc rn (Quick D ra w r 
GX) 64 

gxPortMa pPa ttc rn (Q u i ckD ra w 
GX) 64 

GXPrimitiveShape 66 
GXPrintingEvent, overriding 32, 
36 

GXPrintPage 42 
GXRemoveQDTran slater 40 
GXRotateShape 56 
GXRotateTransform 55 
GXScaleShape 56, 66 
GXSetBitmap 49-50 
GXSetBitm a pParts 64 
GXSctPictu rcParts 67 
GXSetPixel Shape 64 
GXSetShapeAttributes 51,53 
GXSetShapeBounds 66 
GXSetShapelextAttributes 66 
GXSetShapeType 59 
GXSimplify Shape 64 
GXSkewTransform 55 
GX Start Page 42-43 
GXUnlockShape 53 
GXUpdateJob 32-33 

H 

HandleEvent method (OpenDoc) 
12,13 

Hersey, Dave 24 

i 

Icon Utilities, Macintosh Q & A 
105 

idle time, OpenDoc and 12-13 
“Implementing Inheritance In 
Scripts” (Smith) 89-99 
inheritance, implementing in 
scripts 89-99 
indexed bitmap shapes 

(QuickDraw GX) 49, 54-55 


INDEX 125 




Ini t P a r t F ro m Star a ge me the d 
(OpenDoc) 14 

InitPart method (OpenDoc) 10 
Installer, Macintosh Q & A 

107- 108 

j 

job collections (QuickDraw GX) 
28 

Johnson, Dave 110 

K 

kApplltemHit (Color Picker 
Manager) 78 
kCancelHit (Color Picker 
Manager) 78 

kColorChanged (Color Picker 
Manager) 78 

kDidNothing (Color Picker 
Manager) 78 

k New Picker Chosen (Color Picker 
Manager) 78 

kOKHit (Color Picker Manager) 
78 

“KON & BAL’s Puzzle Page” 
(Othmer, Leak, and Newman), 
Heaps of Fun 117-123 
kOSAModeDontStoreParent, 
script inheritance and 93 
kXMP P n >pC( >n tc n ts (( ) pc n D o c) 
10, 14 

L 

Leak, Bruce 117 
LoadSeg, KQN & BAL puzzle 
120-123 

M 

Macintosh AV models, using the 
sequence grabber 87-88 
Macintosh Q & A 100-109 
MacsBng, KON & BAL puzzle 

117 

MailBlocklnfo, Macintosh Q & A 

108- 109 

“Making the Most of QuickDraw 
GX Bitmaps” (Surovell) 48-64 
math library (QuickDraw GX) 62 
MC M ovi e Cha nge d, Ma ci ntosh 
Q & A 103 " 

media capture, using the sequence 
grabber 85-88 

me mo ry u sage, Po we rP C 17-19, 

22 


Message Manager (QuickDraw 
GX) 28-29 

message overrides (QuickDraw 
GX) 28-29 

MessagePad, Newton Q & A 112 
mlnfo (Color Picker Manager) 72 
morph tables, generating 
checksums 4 

MovcHHi, KON & BAL puzzle 
123 

My Ad justFo miats (S i mp le 
Sample) 39, 40 

MyAdjustMenus (Simple Sample) 
34 

My Ad j u s tM e nusFo rP ri ntDi alogs 
(Simple Sample) 36 
MyCleanUpGXlfP resent 
(QuickDraw GX) 30^1 
MyColorChanged 1 J roc (CoI or 
Picker Manager) 72, 73 
MyConveriMenu l tern (Simple 
Sample GX) 35 
MyCreateDocument (Simpie 
Sample GX) 3L 32 
MyDisposeDocumen t (Si mpl e 
Sample GX) 31, 38 
MyDisposePage (Simple Sample 
GX) 37-38 

MyDocumentRec (Simple Sample 
GX) 31 

My 13 o Cus tom Page S e tu p (Si m p le 
Sample GX) 36 
M yD oM enuC ]ommand (Si mpi e 
Sample GX) 34-35 
MyDoPageSetup (Simple Sample 
GX) 36 

MyGXPrintLoop (Simple Sample 
GX) 41-42 

My I n i tGXIfP res e nt (Simple 
Sample GX) 30 
MylnsertPage (Simple Sample 
GX) 37 

MyLoadPrint jnf o (Simple Sample 
GX) 33 

MyPrintAShape (Simple Sample 
GX) 43 

MyPrintDocument (Sim\)1 e 
Sample GX) 36-37 
MyPri ntin gE ventO verri de 
(Simple Sample GX) 32 
MyPrintOneCopy (Simple Sample 
GX) 44-45 

MyRep I aceCollecti onltem (S i mpl e 
Sample GX) 45 
MySaveFormatRefs (Si mple 
Sample GX) 39 


MySavePrintinfo (Simpie Sample 
GX) 33, 39 

N 

NewCollection (QuickDraw GX) 
28 

newColorChosen (Color Picker 
Manager) 72 
Newman, Steve 1 1 7 
Newton Q & A: Ask the Llama 
112-116 

o 

oapp\ script inheritance and 97 
offscreen drawing, with 
QuickDraw GX 61 
offscreen library (QuickDraw GX) 
62 

OKToClose, KON & BAL puzzle 
120 

OpenDoc 6-16 

documents tor age 13-15 
drawing code 10-11 
even t handling 12-13 
freeing memory 1 6 
initialization code 9-10 
object classes (listed) 8 
and resources 9 
shape negotiation 1 1 
Open Seri pting Archi teeture 
(OSA), script inheritance anti 
89-90, 98 

OSADo Event, script inheritance 
and 98 

OSAGetProper ty, scri pt 
inheritance and 93 
OSASetProperty script 
inheritance and 93,98 
O S AS to re, sc r i pt inheri la n ce a n d 
93 

Othmer, Konstantin 117 
oval library (QuickDraw GX) 62 

P 

Page Setup dialog, QuickDraw 
GX and 35-36 
paper-type co 1 lecrions 
(QuickDraw GX) 28 
pa rt h a n d I e rs (Open Do c) 6-16 
partlnfo field (OpenDoc) 14-15 
part objects (OpenDoc) 7, 8 
parts (OpenDoc) 7 
PBGetCatlnfo, Macintosh Q & A 
105, 106 


126 develop l&sue 19 September 1994 





' P D E F' 10 resoy rce s, Q u i ckDraw 
GX and 26 

pdoc' Apple event handler 
(QuickDraw GX) 46-47 
PicHandle (QuickDraw), 

converting to gxPicture shapes 
40 

PickColor (Color Picker Manager) 
69, 70-72, 74 
pickerType (Color Picker 
Manager) 71 

“Pick Your Picker With Color 
Picker 2.0” (Holland) 68-84 
Ptersol, Kurt 6 

p i xe IS i ze val u es (Qu i ckD raw G X) 
48, 50 

pixMaps (QuickDraw) 48 
versus bitmaps 61 
place Where (Color Picker 
Manager) 71 

PostScript code, QuickDraw GX 
and (Macintosh Q & A) 
101*102 

Powe r Macintos h, d e si gning 
applications for 20-23 
PowerPC, tuning memory usage 
17-19, 22 

PreFlush, KON & BAL puzzle 
118, 120 

PrGeneral, Macintosh Q & A 101 
Print dialog, QuickDraw GX and 
36-38 

pri ntNextPageScri pt, Newton 
Q&A 112 

Print One Copy command, 
QuickDraw GX and 34-35 
Process Manager, Macintosh 
Q&A 105 

prompt field (Color Picker 
Manager) 72 

proto R( >11, Newton Q&A 112 

Q 

q d li brary (Qui ckD raw GX) 6 2 
Qui ckD raw a pp 1 i catic >ns, 

compatibility with QuickDraw 
GX 24-47 
QuickDraw GX 

clip pi ng effect 65-67 
com pa ti bil i ty with n on- 
QuickDraw GX 
applications 24-47 
creating bitmap shapes 
48-49 

d i s k-b a sed b i tin a p sha pes 
51-53 


indexed bitmap shapes 49, 
54-55 

libraries 62-63 
manipulating bitmap shapes 

49-64 

morph tables 4 
page-to-fonnat 

co r r es po n den ces 38-39 
pixel value representation 
50 

PostScript code and 
(Macintosh Q & A) 
101-102 

printer drivers (Macintosh Q 
& A) 100-102 
P ri n ti i \g Ma n a ger a n d 31 
shape caches (Macintosh Q 
& A) 100 
transfer modes 60 
t r ansi a tin g Q ui ckD ra w 
commands 3 9-44 
Quick Take, Macintosh Q & A 
107 

QuickTime 2,0, media capture 
using the sequence grabber 
85-88 

R 

ra m p lib r a ry (Qu i ck I ) raw GX) 6 2 
Rea Hoc Handle, KON & BAL 
puzzle 122 

Redo method (Open Doc) 13 
registration of components, 
Macintosh Q & A 107 
Robbins, Greg 20 
ROM_coverPa ge Fon n a t, N e w ton 
Q&A 112 

root parts (OpenDoc) 9 
Run Apple event, script 
inheritance and 97 
runtime objects, in OpenDoc 7-8 

s 

Save As, KON & BAL puzzle 120 
scripts, implementing inheritance 
89-99 

seq Gra h Play Duri ngRecord 
(sequence grabber) 87 
sequence grabber, media capture 
85-88 

session object (OpenDoc) 7-8 
set associative caches, PowerPC 
and 17 

SetPickerProfile (Color Picker 
Manager) 77 


SetValue, Newton Q&A 

115-116 

S GGetC h a n ne 1 Setti n gs (se q u enee 
grabber) 87 

SGIdle (sequence grabber) 87 
SGInitialize (sequence grabber) 

85 

SGNewChannel (sequence 
grabber) 86 

SGNe w Channel F r o m C on i p on ent 
(sequence grabber) 86 
S GS e tCba nne 1B ou n ds (seq u e n ee 
grabber) 86, 87 

SGSetChannelSettings (sequence 
grabber) 86 

S G S e tC di a n n el Usage (sequence 
grabber) 86, 87 
SGSetDataGutput (seq uen ce 
grabber) 87 

S C I S e tC i Wo rl d (s eq u enee gra b b er) 

86 

SGStartPreview (sequence 
grabber) 86 
shapes (OpenDoc) 11 
shared handlers, script inheritance 
and 94-98 

signatures, deleting 104 
Simple Sample application 
(QuickDraw GX) 29, 3 1 
SimpliFace2 sample program 90, 
95,97 

script inheritance hierarchy 
91, 95 

Smith, Paul G, 89 
SM PEn ume rate Blocks, Macintosh 
Q&A 108 

SOM (System Object Model) 
(IBM) 6-7 

“Somewhere in QuickTime” 
(Wang and Urbina), media 
capture using the sequence 
grabber 85-88 

StartMovie, Macintosh Q & A 
102-103 

StartUsing, script inheritance and 
97 

static data, editing (Newton 
Q&A) 114 

storage library (QuickDraw GX) 
63 

storage unit objects (OpenDoc) 

10 

Surove 11, David 48 
system-owned dialogs, Color 
P i eke r M a n a ge rand 72, 

74-75, 81 


INDEX 127 







T 

tag (QuickDraw GX) 27 
tag list position (QuickDraw GX) 
27 

TEGetOffeet, Macintosh Q & A 
109 

transferMode library (QuickDraw 
GX) 62-63 

transfer modes (QuickDraw GX) 
60 

transforms 

OpenDoc 1 1 
QuickDraw GX 55 
TrapAvailable, Macintosh Q & A 
105 

T S cri p ta hi eO b j ect:: S e tP top e rty, 
script inheritance and 94 
TScriptableObject::StartUsing, 
script inheritance and 97 
TS criptAdmi ni str ato r;; 
GetAttaehedScript script 
inheritance and 96 

u 

Undo method (OpenDoc) 13 
undo stack object (OpenDoc) 8 
Update Status, Newton Q & A 
113-114 

Urbina, Fernando 85 
used shape (OpenDoc) 1 1 

v 

vApplieation, Newton Q & A 112 
vCJipping, Newton Q & A 112 
“Veteran Neophyte, The” 

(Johnson), Rubber Meets Road 
110-111 

viewFlags, Newton Q & A 112 
view ports, versus graphics ports 
(QuickDraw GX) 59-60 
viewSettipForm Script, Newton 
Q & A 112, 115 
virtual function calls, KON & 

BAL puzzle 118-119 
vVisible, Newton Q & A 112 

w 

WaitNextEvent 

OpenDoc and 12 
Power Macintosh and 23 
Wang,John 85 

x 

XMPArbitrator (OpenDoc) 8 


XiVlPDispatcher (OpenDoc) 8 
XMPFacet (OpenDoc) 8, 9 
XMPFrame (OpenDoc) 8, 9 
XMPPait (OpenDoc) 8-9 
XMPPart: :AbortRelinquishFocus 
(OpenDoc) 15 

XMPPart:: BeginRelinqmshFocus 
(OpenDoc) 15 

XMPPart: :Commi tRelinquishFocus 
(OpenDoc) 15 
XMPPart: :Focus Acquired 
(OpenDoc) 16 

XMPPart:: Focus Lost (OpenDoc) 
16 

XMPPart: :Han dl eEven t 
(OpenDoc) 12 

XMPPart::Purge (OpenDoc) 16 
XMPP a rt:: Read Pa rtl n fo 
(OpenDoc) 15 
XMP P a rt:: Writ ePa rtln fo 
(OpenDoc) 15 
XMP prefix (OpenDoc) 6 
XMPSession (OpenDoc) 7-8 
XMPStorage U n it:: DeleteValue 
(OpenDoc) 14 
XMPStorageUnitcGetOffset 
(OpenDoc) 14 
XMPStorageUnit::GetValue 
(OpenDoc) 14 

XMPStorageUnit::InsertValae 
(OpenDoc) 14 
XMPStorageUnit::SetOfifset 
(OpenDoc) 14 
XMPS tora geU n i t:: S e tVa I ue 
(OpenDoc) 14 
XMP Un d o (O pc nD oc) 8,13 
XMPU n d o:: Ad d Acti n nl h H isto ry 
(OpenDoc) 1 3 

XMPUndo::Redo (Open Doc) 13 
XMPUndo::Undo (OpenDoc) 13 

Y 

YUV compression, sequence 
grabber and 87-88 

z 

zone names, Macintosh Q & A 
108 


128 develop Issue 1 9 September 1 994 








RESOURCES 


Apple provides a wealth of information, 
products, and services to assist 
del'elopers. A PDA, Apple's source for 
developer tools, and Apple Developer 
University are open to anyone who 
wants access to development tools and 
instruction. Developers may access 
additional information and services 
through Apple's Developer Programs. 


APDA To order products or receive o 
complimentary catalog, call 1 -800-282- 
2732 m the U.S., 1-800-6370029 in 
Canada, [716]871-6555 internationally, or 
[716)871-6511 For Fox, You can also order 
electronically (AppleLink APDA; Internet 
apda@applelmk,apple.com; America Online 
APDAorder; or CompuServe 76666,2405) 
or write APDA, Apple Computer, Inc., P.O. 
Box 319, Buffalo, NY 14207-0319. 


APDA offers convenient worldwide 
access to development tools, 
resources, training products, and 
information for anyone interested in 
developing applications on Apple 
platforms. Customers periodically 
receive the APDA Tools Catalog 
featuring hundreds of Apple and 
third-party development products. 
There are no membership fees. 
APDA offers convenient payment 
and shipping options, including site 
licensing. 

Apple Developer University 

(DU) provides training designed to 
increase your software development 
productivity. The curriculum 
includes courses to get you started 
programming on Apple platforms, 
as well as advanced, in-depth 
training on the newest Apple 
technologies, such as PowerPC, 
OpenDoe, QuickDraw GX, and 
Newton. DU offers courses in 
Cupertino CA and at selected 
training locations. The DU 
Extension partner located in 
Portsmouth NH also schedules 
selected courses in its facilities. 

In addition to classroom training, 
DU offers multimedia self-paced 
courses and low-cost mini-course 
tutorials. 

The Associates Program is Apple's 
primary program for developers 
across all Apple technologies, 
including Macintosh, Personal 
Interactive Electronics (such as 
Newton), and multimedia. It's a 


Apple Developer University The 

registrar at [408)9744897 can reserve 
your place or send a current Curriculum 
Guide and Course Schedule. You can also 
send an AppleLink to DEVUNIV or write 
Developer University, Apple Computer, Inc., 
One Infinite Loop, M/S 305-1TU, Cupertino, 
CA 95014. Self-paced products should be 
ordered directly through APDA. 


low-cost, self-support program that 
also provides a connection with 
Apple and fellow developers, 
information on new technologies, 
and discounts on equipment. 

The Apple Multimedia Program 

is designed for developers interested 
in the emerging multimedia market. 
Program features include a quarterly 
mailing and discounts on third-party 
products, training, and events. 

The Macintosh Technology 
Partners Program is open to 
Apple-selected strategic developers 
focused on Macintosh technology, 
including PowerPC, QuickTime, 
QuickDraw GX, and PowerTalk. In 
addition to receiving the same 
development information and tools 
as members of the Associates 
Program, Macintosh Technology 
Partners receive programming-level 
development support via electronic 
mail. Membership in this program is 
limited to strategic developers who 
directly contribute to Apple's long¬ 
term product plans and business 
objectives. 

The PIE Partners Program is 

open to Apple-selected strategic 
developers focused on Personal 
Interactive Electronics. It offers the 
same core features as the Associates 
Program, but also includes 
progra mmin g- level tiev el i jpment 
support via electronic mail, 
additional hardware purchasing 
privileges, marketing programs, and 
media production assistance. 


Apple Developer Programs Call the 
Developer Support Center at (408)974- 
4897, AppleLink DEVSUPPQRT, or write 
One Infinite Loop, M/S 3G3-2T, Cupertino, 
CA 95014, for information or an application 
form. Developers outside the U.S. and 
Canada should instead contact the Apple 
office in their country for information about 
developer programs. 
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